Kessinen/noteman-slicer
1
0
Fork 0
Code Issues 8 Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: Kessinen/noteman-slicer:efc920fdc5664426badf9cd31cb412338174dcff
Branches Tags
Kessinen/noteman-slicer:main Kessinen/noteman-slicer:dev
...
compare: Kessinen/noteman-slicer:dev
Branches Tags
Kessinen/noteman-slicer:dev Kessinen/noteman-slicer:main
26 Commits
efc920fdc5 ... dev
Author SHA1 Message Date
Esa Kataja 68e41c2470 Give the editor a visual identity and a real levels control 
The panel now uses the same colours the page is drawn with, on dark
chrome so the scan is the brightest thing on screen. Levels move from two
anonymous sliders to the scan's own histogram with draggable black and
white points and a tone strip, since getting them wrong is the one
mistake that only shows up on the tablet. A page rail replaces the
stepper and carries each page's slice count; export is pinned below the
scroll instead of below the fold; marker types read as prose.
 2026-07-29 15:39:24 +03:00
Esa Kataja cdf37302d7 Ask before reopening a bundle that carries no cuts 
A bundle without a source block cannot be round-tripped, but its PDF can
still be cut from scratch. Offer that instead of refusing: confirm, run
detection, and line the markers up by position when the slice counts
match exactly.
 2026-07-29 15:06:45 +03:00
Esa Kataja 61b8ec8301 Make a bundle reopenable, and number slices 
A bundle was a one-way trip. The slice images are output and the cuts
that produced them lived only in the producer's own project file, so a
bundle someone handed you meant cutting the score again from scratch.

The manifest now carries the geometry, in a `source` block: per page the
cut polylines, skew, levels and content rectangle, all in normalised
coordinates so they survive any render resolution, and per slice the page
and slot it came from. Discards are stated by omission — a slot no slice
claims was discarded — since shipping a discarded slice's image would
defeat discarding it.

`noteman-slicer open song.zip` unpacks the archived PDF, rebuilds the
project from that geometry, restores markers, engravings and the title
block, and opens the editor. Jump destinations go back from an array
index to the (page, slot) the editor works in. The images in the zip are
discarded: the PDF is what the pipeline renders from. Re-exporting a
reopened bundle reproduces its manifest exactly. It refuses to overwrite
a PDF or project file already sitting there, because the obvious place to
unpack is where someone's unfinished cuts live.

Separately, every slice can now carry the measure it starts at, not just
a re-engraved one — a scanned system is numbered in the score the same
way, and noteman wants to answer "take it from bar 33" about either. It
moves off the replacement onto the page, alongside markers and discards,
and out of the bundle's engraving object onto the slice.
 2026-07-29 14:30:54 +03:00
Esa Kataja 8f670cf7db Engrave window: bar numbers, and two silent LilyPond faults 
A system can now be given the measure it starts at, in a First bar field
beside key and time. Per slice, since it is the one thing about a
replacement that cannot be inherited from the song. Bar numbering is a
Score property, so it is set once on the first staff, and made visible
only at a line beginning — that vector is fussy: #(#f #t #t) also prints
a number mid-system and #(#f #t #f) prints the second bar's rather than
the first's. It travels in the bundle's engraving object as `bar`.

Two things LilyPond 2.24 was quietly refusing to draw:

`\bar ":|"` and the other old repeat names produce nothing at all — no
error, no warning, exit status 0, just a missing repeat that you find on
the tablet. Every book and forum answer still uses them, so translate
them to the modern spellings.

`\clef treble_8` unquoted is not an octavated clef either. It parses as a
plain treble plus a stray "8" markup that lands under the first note, and
the staff then reads an octave off — a tenor line engraved at soprano
pitch. Quote it.

The source pane, which is where either of those would have been visible,
is now a collapsed section at the bottom rather than a permanent slab. It
uses the panel's own disclosure helper, lifted out of Editor so both can
call it.
 2026-07-29 13:44:42 +03:00
Esa Kataja 24b12214bb Fit the page on startup, name the bundle, show the selection 
Three things a first session trips over.

The editor opened at an arbitrary zoom. show_page does fit the page, but
it runs before the window has been laid out, when the viewport is still
its default size; redo it once when the real size arrives.

The bundle was named after the PDF, which is whatever the download was
called. Take the song's title instead — unsafe characters dropped, then
whitespace collapsed to dashes. Accented letters stay, since ä and ö are
not a filesystem's problem, but a leading dot would hide the file.

And the selected slice was drawn as an outline whose top and bottom edges
run under the cut lines painted over them, leaving two thin verticals in
the margins and no way to tell what was selected. Wash the slice, as the
discard and engraved states already do, and keep the outline for the trim
anomalies it exists to show.
 2026-07-29 13:09:27 +03:00
Esa Kataja 19f28f4da8 Propose black and white points from the scan 
Levels shipped at 0–255 unless someone moved the sliders, and Bicycle
Race showed what that costs. Its ink is grey, not black — a scanned
engraving, ink at 2–95, paper at 163–255 — and with alpha = 255 − luminance
that greyness becomes transparency. No pixel in the exported bundle was
even fully opaque, and the downscale to the song's width blended every
stroke edge further. Nothing downstream can rescue it.

So detection proposes levels too, like it proposes cuts and skew.
Notation is two-tone, which makes Otsu's split the measurement wanted;
the points sit halfway from it to each end of the range, so the ramp
between them survives as antialiasing rather than going jagged. A page
already scanned bilevel has no interior split — Otsu degenerates to 0 —
and is left alone. Per page, with the median becoming the song's, so a
near-blank page cannot set them.
 2026-07-29 12:50:37 +03:00
Esa Kataja 38cb6ce09a Stop an edge artefact and a speck filter from destroying a song 
Olukainen juomukainen came out unusable, from two separate faults.

The scanner left a dark line down the sheet edge, running the full height
of every page but the first. Being taller than any bracket it won every
overlap in anchor selection and swallowed the page into one system, so
five pages of six proposed no cuts at all. A page's brackets and barlines
are all about one system tall, so a stroke far taller than the typical
one is not notation — relative to the page's own strokes, since a page
holding one big system is legitimate.

The trim then removed each system's bottom line of lyrics. It judged ink
blobs by area, and a letter is nowhere near the threshold; a whole line
of them is dozens of blobs, none of which qualifies. Measure ink per row
and per column instead — a line of text carries plenty in total, and a
fleck's row carries almost none, which is the case the filter was for.

Detection now finds three systems on every page of that score, and every
slice keeps all four voices' words.
 2026-07-29 12:22:08 +03:00
Esa Kataja 2a22fc469f Honour a page's /Rotate when extracting a scan 
A scan fed sideways stores its image landscape and sets /Rotate 90 so a
viewer turns it upright. Extracting the image by xref — which is how a
raster source is read, to keep the scan's native resolution — bypasses
that, so every system ran down the page and detection found nothing.

Apply the page rotation to the extracted raster. Quarter turns only;
nothing produces anything else.
 2026-07-29 12:08:45 +03:00
Esa Kataja cf1344c5bf Carry a re-engraved slice's notation in the bundle 
A replaced slice shipped as pixels only, so the LilyPond behind it died
with the project file — and a project is spent once exported. Correcting
one wrong note meant retyping the system.

Slices gain an optional `engraving` object: the language, key, time and
one entry per voice holding the notes and lyrics verbatim. Structured per
staff rather than one blob of source, because that is what both a later
edit and a MIDI render want; song-level key and time are resolved per
slice so reading one needs no context from its neighbours.

Additive and ignorable, so the format stays at version 1.
 2026-07-29 11:42:44 +03:00
Esa Kataja 630541c0cd Add a getting-started guide 
A first user hit a wall at the door: the README still said "design only,
no code yet", and nothing anywhere said how to drive the editor.

docs/guide.md walks one PDF to one bundle — install, the five per-page
decisions, markers and jump targets, the title block, export — with a
mouse/key table and the failures that actually happen. The README's stale
status and installation lines go with it.
 2026-07-29 11:42:36 +03:00
Esa Kataja b594968bb8 Add optional bilevel shrinking of the archived PDF 
Scanned scores are black ink on white paper stored as 8-bit greyscale or
RGB, which costs several times what the same page costs as a bilevel
image. Across an 11-song corpus this is 27.6 MB to 7.7 MB; Engel's
bundle goes from 5997 KB to 2092 KB with byte-identical slices, since
only the archived copy changes.

Three approaches were measured and discarded first, which is worth
recording because two of them are the obvious ones. Converting RGB to
greyscale and re-encoding makes these files 20-86% LARGER: the source
JPEGs are already near 0.7 bits per pixel, so re-encoding adds
generation loss and spends more bits than the original did, and dropping
chroma recovers nothing because JPEG already subsamples it. Lossless
structural optimisation gains 0.1%, because images are 99% of every file
and there are no duplicates. Downsampling works but 300 DPI is print
resolution, and the PDF exists to be printed.

Two failure modes were found by looking at output rather than at byte
counts, and both are now refused:

- A scan at ~115 DPI came back with broken staff lines. Guarded on
  resolution as the image is *placed on the page*, so a tiled scan with
  126 small images still qualifies where a pixel count would reject it.
- Cover artwork was flattened to grey. Guarded on chroma: artwork
  measures 44% off-grey against 3% for sensor tint on a greyscale scan.
  The first threshold of 2% was a false positive that cost 685 KB on one
  song for nothing; 10% sits in the gap with room either side.

Exposed as a button rather than a checkbox. It reports what it skipped
and why, and shows a before/after crop, because the failure it can
produce is obvious at a glance and invisible in a size figure. Off by
default: this is lossy on the copy kept for printing.
 2026-07-29 10:42:59 +03:00
Esa Kataja b8d93cee47 Specify the Score Bundle Format, and make tempo an integer 
The bundle is documented as a standalone format rather than as a note
between two programs: producers and consumers are generic, the marker
vocabulary is defined musically rather than by what a viewer does with
it, and image properties are stated as guarantees with the reasoning
where it is not obvious. Anything that reads scores can implement it
without knowing this tool exists.

Taking that view changed the substance in three places. Marker types now
carry their musical meaning rather than a UI mapping. The rule against
re-importing became a statement about identity - indices mean something
only within one bundle, so two bundles of a piece are independent
documents. And forward-compatibility rules were added, which a protocol
needs and a handover note did not: ignore unknown fields and marker
types, refuse an unknown version.

Tempo is now an integer, beats per minute, exported as a JSON number and
omitted when blank; the editor accepts digits only. A figure can drive a
metronome or a click track where a verbal marking cannot, and readers do
not agree on what Andante means. This needs the consumer's column
changed from free-form text, which the format document flags.

Every figure in the document comes from a real export.
 2026-07-29 09:22:43 +03:00
Esa Kataja 97c8e8a709 Add LilyPond slice replacement with a structured engrave window 
Re-engraving is a rescue path for the handful of systems a scan cannot
deliver, so the window is an editing surface rather than an automation
project. Three full-width rows - the scanned system, the render, the
form - because a system is wide and short and the job is comparing one
against the other bar by bar. The render is shown scaled to the scan's
staff height, which is what export does anyway, so it previews the real
thing.

A form rather than a text box. Key and time are slice-level, clef,
notes and lyrics per voice: every staff in a system carries the same key
signature, and Kaipaava proves it across five-staff and two-staff
systems alike. Notes and lyrics stay raw LilyPond, so slurs, dynamics,
tuplets and the laissezVibrer/repeatTie idiom for ties crossing into the
next slice all work untouched.

Notes are entered in \relative mode, referenced to the middle of each
clef's staff, so a part needs no octave marks at all in the common case.

The time signature is used for spacing and bar checks but not printed:
the printed score repeats the key at every system and the time only at
the first, so a re-engraved middle slice showing one would stand out.

Seeded from what can be known reliably. Voice count comes from counting
staves in the slice; key, time and clefs are inherited from the song,
because the slices being re-engraved are the illegible ones and reading
a key signature off them is exactly the measurement that fails. After
the first replacement in a song only the notes need typing.

Staff counting needed two corrections against the corpus: compare gaps
against line spacing rather than staff height, since adjacent staves can
sit closer together than one staff is tall; and require five lines in a
group, since Engel's 'uh______' lyric extenders are long horizontal runs
too and each counted as a staff. Kaipaava now reads 2,2,2,2,5 on page 1,
Ketun 6, Engel 4.

Also in this change:

- Title is required for export, every other metadata field optional,
  enforced in bundle.write so the CLI and the editor both get it. Tempo
  added; noteman already has a free-form column for it.
- The panel is a splitter rather than a fixed width, sections collapse
  under bold grey disclosure headers, and it scrolls.
- A re-engraved slice is washed amber with an ENGRAVED badge, and
  markers get badges too. Thin coloured text was invisible against a
  scan.

Closes #31
Closes #32
Closes #33
Closes #34
 2026-07-29 01:29:43 +03:00
Esa Kataja ff1cc6740e Add markers: placement, labels and click-to-pick jump targets 
Markers are stored per (page, slot), parallel to the discard flags, so
adding or removing a cut keeps them aligned with their slices. On a
split they stay with the upper half: a marker sits on a printed symbol
and nothing can say which side that symbol landed on, so predictable
beats clever.

Jump targets are chosen by clicking the slice rather than from the
thumbnail strip the plan called for. Less code, and it reads the score
instead of a list of thumbnails - which is what you want when hunting
for the Coda sign. Any page; PageUp/PageDown while picking.

Export resolves (page, slot) to the bundle's array index, the only
cross-reference the format has. A jump whose target was discarded or
re-cut away is dropped rather than exported dangling, since noteman
would have nothing to resolve it to.

tests/test_markers.py covers the enum size - that is the coupling
between two repos - along with cut-edit alignment, index resolution,
the dangling-target drop, and round-trips through both the project file
and a real bundle.

Closes #28
Closes #29
Closes #30
 2026-07-29 00:05:48 +03:00
Esa Kataja 15f64e4131 Record the spent-project reversal as ADR 0007 
The project file existed to persist state, so a future reader finding
the exported flag would otherwise re-litigate it. The ADR states plainly
that this reverses an earlier decision, what the original reasoning was,
and what changed in use.

ADR 0002 deferred the SVG renderer partly because re-export made it free
to add later. That no longer holds, so its 'not stranded' bullet is
struck through and pointed at ADR 0007 rather than left standing to
mislead whoever revisits the SVG question.
 2026-07-28 23:51:53 +03:00
Esa Kataja b6847a06ee Treat a project as spent once its song has been exported 
Opening an exported song starts a fresh session from detection instead
of resuming: cuts, discards and metadata do not carry over, so a re-cut
never inherits decisions that have already shipped. --resume overrides
it on edit, export and project.

This reverses what was agreed in planning and written into docs/spec.md
and CONTEXT.md, which promised resume-across-sessions and re-export.
Both are corrected. The cost is deliberate and worth stating: changing
the width cap or adding the SVG renderer later now means re-cutting each
song by hand rather than regenerating every bundle from its project
file.

Export records the flag in bundle.write, so no caller can forget it.

Also removed --refit and the Auto-fit buttons, which were added without
being asked for and whose only purpose - migrating projects made before
the content rectangle was proposed - disappears once exported projects
start fresh. Reset now restores detection's proposal rather than the
whole page: clearing to full width would undo the thing the rectangle
exists for, so one button covers it.

open_project() replaces four copies of load-or-detect across the CLI
and the editor.
 2026-07-28 23:49:03 +03:00
Esa Kataja 54b8e37657 Add project --refit to re-propose the content rectangle 
Saved state always wins over a fresh proposal, which is what the
project file is for — but it also means a project made before detection
proposed a content rectangle keeps the old whole-page one forever, and
reopening or re-exporting changes nothing.

--refit re-runs the proposal over every page while leaving cuts,
discards, stepped cuts and metadata untouched. Verified on the real
Engel project: rectangles updated on all 6 pages, all 4 cuts per page
kept including both stepped ones, metadata intact, and exported slices
scale larger now that the margin shadow no longer pads the width.

--force remains the destructive option that re-detects everything.
 2026-07-28 23:35:10 +03:00
Esa Kataja c00a00bb2a Propose the content rectangle from the staff lines 
Both scan problems reported from testing came from the same place: the
content rectangle defaulted to the whole page, so the mechanism meant
to handle margin junk never engaged. Ketun joululaulu has a vertical
scan streak down the right margin and Engel a shadow, and because trim
is tight and per slice, either one sets that slice's width, which sets
the song's widest slice, which scales the whole song down.

Detection can propose it. Staff lines are long horizontal runs; scan
shadows, spine darkening and glass streaks are vertical, so a wide flat
opening keeps one and erases the other. Three corrections were needed
against the corpus:

- Search only rows inside detected systems. A horizontal artefact above
  or below the music is itself a long horizontal run reaching the paper
  edge, which put Engel's left bound at 0.
- Take a percentile of the staff-line extents, not the maximum. Where
  an artefact touches a staff line the two merge into one component: on
  Ketun p2 the merged line ends at 1575px against 1544px on the clean
  page.
- Take the left bound from the brackets too. A bracket sits left of
  every staff line, so a staff-line bound crops it off — visible
  immediately when comparing exported slices.

Anchors are now a dataclass carrying their left edge rather than a
(top, bottom) tuple.

Engel now drops 12-14% of page width and its music fills 1920px instead
of leaving the shadow's dead space; Ketun drops 12%.

Existing projects keep their saved rectangle; the editor's new Auto-fit
and Auto-fit all buttons re-propose it without disturbing cuts.
 2026-07-28 23:28:45 +03:00
Esa Kataja bc19eae111 Add the editor: page view, cut editing, discard, levels, metadata 
QGraphicsView for the viewport, with cuts and the content rectangle
manipulated by hit-testing in the view rather than as movable items —
the geometry is normalised, so what the screen shows and what the
renderer uses are the same numbers at a different zoom.

Cuts are edited as polylines: double-click adds one, drag moves it,
Ctrl-click inserts a vertex, right-click deletes a vertex or the whole
cut. That is how a straight cut becomes the stepped cut Engel needs.

Slice boundaries are drawn, not just cut lines, so a trim anomaly is
visible before export rather than after. Discarded slices are shaded.

Pages preview at 1800px regardless of source resolution, cached per
page, because re-reading a 4959x7017 vector render on every slider move
is unusable.

Autosave is debounced at 800ms and also fires on close.

Closes #12
Closes #14
Closes #15
Closes #16
Closes #17
Closes #18
Closes #19
Closes #20
Closes #26
 2026-07-28 23:03:49 +03:00
Esa Kataja 974c91a727 Add the render pipeline and bundle export 
Project state plus PDF in, finished slice images out. Slices are cut as
polygons rather than row ranges, so a stepped cut yields a slice with a
transparent notch instead of one that covers its neighbour.

Masking paints white, which the ink-to-alpha step turns into full
transparency — the same outcome the spec asks for, one step earlier.

Scale normalises every slice to the median staff height before fitting
the song to 1920px, so a rescanned page sits at the same note size as
its neighbours. The cap only ever shrinks: a song narrower than 1920
stays narrower.

Alpha quantisation rounds to 16 values spanning 0-255 inclusive.
Flooring, as first written, capped full ink at 240 and left every note
6% transparent — caught by decoding an exported slice rather than by
reading the code.

Ketun joululaulu exports 24 slices at a uniform 1489px, under the cap
and correctly not upscaled from its 200 DPI source; Feliz Navidad 20;
Elaman nalka 18.

Closes #21
Closes #22
Closes #23
Closes #24
Closes #25
Closes #27
 2026-07-28 23:00:53 +03:00
Esa Kataja 9ed38323ef Add project state with cuts, discards and atomic save 
Everything the human decides, in normalised page coordinates so the
file is independent of DPI and of which renderer produced it. The
bundle will be generated from this, which is what makes re-export
possible without repeating human work.

Cuts are polylines from the start, two points being the ordinary
straight case, so the stepped cuts Engel needs are a data question
rather than a migration. Adding a cut splits a slice and copies its
discard flag to both halves; removing one merges them.

Boundary cuts belong here rather than in detection: detection emits
cuts only between systems, so a page would have exactly as many slices
as systems, with the header and footer inside the first and last.
Isolating and discarding them is a slicing decision.

Saves are write-then-rename, so a crash mid-save cannot destroy the
previous state. The PDF is hashed, not copied, so an edit underneath is
reported rather than silently re-cut.

Ketun joululaulu now yields 24 kept slices over 12 pages and Feliz
Navidad 20 over 4, with headers and footers discarded on every page.

Closes #10, #11, #13
 2026-07-28 22:49:51 +03:00
Esa Kataja 61dac44037 Give each ink run a single owner, by precedence not proximity 
Feliz Navidad exposed two assignment faults. Each bracket was expanding
independently, so a lyric line between two systems could be claimed by
both, producing overlapping extents. And nearest-bracket is the wrong
rule: engravers space lyrics generously, so a line sits 43px under its
own system's bracket but only 10px above the next one's.

Now one pass assigns every run exactly once: ink overlapping a bracket
belongs to it, and otherwise the system above wins over the system
below. Text under a staff belongs to that staff.

Known limit, documented in _assign: where a lyric is printed tight
enough that no blank row separates it from the next system's staves,
the two fuse into one ink run and no row profile can split them. The
lyric goes to the system below and the cut lands ~90px high. Dragging
it is the fix.

Feliz Navidad now reads 5 systems on every page, staff 70px, with no
overlapping extents; Ketun joululaulu, Engel and Elaman nalka are
unchanged.
 2026-07-28 22:46:27 +03:00
Esa Kataja 6ff956a622 Add detection: skew, system anchors, ink extents, cuts, staff height 
Systems anchor on the vertical bracket and expand over nearby ink, per
ADR 0006. Two corrections the corpus forced:

- Expansion measures distance from the bracket, never from the growing
  extent. A chaining expansion hops between the closely-stacked lines of
  a title block and walks the whole way up the page — on Engel p1 it
  swallowed the title into system 1 and the copyright footer into
  system 3.
- Reach is 1.5 staff heights, which takes in the lyrics below the last
  staff and the tempo mark and INTRO box above the first, while leaving
  the title block and footer out.

Verified against the corpus. Ketun joululaulu: 2 systems per page except
p7 (3) and p12 (1), staff 48px throughout, skew -2.7 to +1.2 per page,
and p2 system 1 spans 179-1071 where its bracket is 177-994 — the
difference being the bottom voice's lyric line. Engel: 2-3 systems per
page, staff 70-72px. Elaman nalka: 3 systems per page, 0 skew, staff
118px at 600 DPI.

The overlay dump is what made both bugs visible, and stays as the tool
for diagnosing a page that comes out wrong.

Closes #4, #5, #6, #7, #8, #9
 2026-07-28 22:38:50 +03:00
Esa Kataja e2f3e8fbdc Add package skeleton, source classification and raster loading 
The pdf module is the whole of M1 except the debug overlay, which needs
detection results to draw.

Source type is detected per PDF by looking for a page-covering image,
and is always reported for confirmation rather than applied silently
(ADR 0004). Rasters are extracted via Pixmap(doc, xref) rather than by
decoding extract_image() bytes, because MuPDF handles JBIG2 and CCITT
scans that no image library will.

Scanned pages are extracted at the embedded image's native resolution;
only vector pages are rendered, at 600 DPI. Verified against the corpus:
Elaman nalka (vector) renders 4959x7017, Ketun joululaulu (scan) loads
1653x2332, Engel (scan) 2552x3504 — and Engel's page 2 is 2480 wide
where page 1 is 2552, so scan width varies within one PDF.

tests/test_pdf.py builds its own PDFs so the check runs without corpus
files, which are copyrighted and gitignored.

Closes #1, #2, #3
 2026-07-28 22:33:26 +03:00
Esa Kataja 01227b3382 Model cuts as polylines, not horizontal lines 
Page 1 of Engel (Bosse/Partitura) has a boxed VERSE 1 label in the left
margin at the same rows as the preceding system's bass lyric line — ink
on both sides of the page throughout the band, so no horizontal line
separates them. The label belongs to system 2, the lyrics to system 1.

A cut is therefore a polyline spanning the page, two points being the
ordinary straight case. A slice bounded by a non-straight cut is not
rectangular: its image is the region's bounding box with everything
outside made transparent, which composites invisibly on the viewer's
sheet. Masking paints transparency, never white.
 2026-07-28 22:22:03 +03:00
Esa Kataja 46ae7e813a Replace the handoff notes with a durable spec and ADRs 
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).
 2026-07-28 22:05:09 +03:00
34 changed files with 6771 additions and 23 deletions
Expand all files Collapse all files
CONTEXT.md
+26 -15
View File
@@ -20,9 +20,11 @@ _Avoid_: mode, format
**Slice**: **Slice**:
The atomic visual unit of a song — one *system*, one full line of music across The atomic visual unit of a song — one *system*, one full line of music across
all voices, typically 4–12 bars with lyrics intact. Same definition as noteman's. all voices, typically 4–12 bars with lyrics intact. Same definition as noteman's.
Structurally, a horizontal region of a page: a page begins as a single slice and Structurally, a region of a page bounded above and below by cuts: a page begins
each cut splits one slice into two, so slices always tile the page with no gaps as a single slice and each cut splits one slice into two, so slices always tile
and no overlap. the page with no gaps and no overlap. Rectangular when its cuts are straight,
and stepped when they are not — the slice image is then its bounding box with
everything outside the region transparent.
_Avoid_: segment, strip, row, band _Avoid_: segment, strip, row, band
**Discard**: **Discard**:
@@ -32,10 +34,11 @@ pre-sets it on a page's top and bottom slice when they contain no system.
_Avoid_: delete, skip, exclude _Avoid_: delete, skip, exclude
**Slice image**: **Slice image**:
The rendered artifact of a slice. From a raster source: lossless WebP, RGB pure The rendered artifact of a slice: lossless WebP, RGB pure black,
black, `alpha = 255 − luminance`, width capped at 1920px — paper is transparency, `alpha = 255 − luminance`, width capped at 1920px — paper is transparency, ink is
ink is alpha. From a vector source: SVG with text converted to paths. Both are alpha. Display-ready as produced; nothing downstream reprocesses it. An SVG form
display-ready as produced; nothing downstream reprocesses them. for vector sources is designed but deferred, which is why the geometry model is
renderer-agnostic.
_Avoid_: PNG, page image, tile _Avoid_: PNG, page image, tile
**Marker**: **Marker**:
@@ -48,9 +51,12 @@ two repos.
**Project**: **Project**:
The persistent state of slicing one song: the source PDF it points at, its cuts, The persistent state of slicing one song: the source PDF it points at, its cuts,
discards, content rectangle, levels, staff-height overrides, markers and discards, content rectangle, levels, staff-height overrides, markers and
metadata. Autosaved beside the PDF; the bundle is generated from it, so any metadata. Autosaved beside the PDF; the bundle is generated from it. One PDF,
export can be regenerated without repeating human work. One PDF, one song, one one song, one project, one bundle — never a many-to-one in any direction.
project, one bundle — never a many-to-one in any direction.
**Spent** once its song has been exported: opening the PDF again begins a fresh
session from detection rather than resuming, so a re-cut never inherits
decisions that have already shipped.
_Avoid_: session, document, edit list _Avoid_: session, document, edit list
**Bundle**: **Bundle**:
@@ -75,11 +81,16 @@ living unenforced in two repos, and a score with two codas simply works.
_Avoid_: link, reference, pointer _Avoid_: link, reference, pointer
**Cut**: **Cut**:
A horizontal line placed on a page that splits one slice into two. Straight at A boundary placed on a page that splits one slice into two. Modelled as a
first; a later polyline form handles pages where systems slant or interleave. **polyline** spanning the page from left edge to right edge, with two points —
Placement is forgiving — anywhere inside the whitespace gap yields the same a straight horizontal line — as the ordinary case. Extra vertices handle the
output, because trim crops to ink afterwards. common publisher habit of printing a section label (`VERSE 1`, `INTRO`) in the
_Avoid_: split, divider, break left margin at the same height as the previous system's lyrics: the cut steps
above the label on the left and below the lyrics on the right.
Placement along the boundary is forgiving — anywhere inside the whitespace yields
the same output, because trim crops to ink afterwards.
_Avoid_: split, divider, break, cut line
**Content rectangle**: **Content rectangle**:
The region of a page that holds music. Set per PDF, adjustable per page, applied The region of a page that holds music. Set per PDF, adjustable per page, applied
README.md
+27 -7
View File
@@ -8,7 +8,8 @@ A slice is one *system* — one full line of music across all voices, typically
scroll, so the slicer's job is to cut a printed page into systems, clean them up 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. 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. **New here? [docs/guide.md](docs/guide.md) walks you through making your first
bundle.**
## How it works ## How it works
@@ -29,21 +30,40 @@ at it.
## Installation ## Installation
Not yet installable. When it is:
``` ```
uv tool install --editable . uv tool install --editable .
``` ```
That puts a `noteman-slicer` command on PATH which runs from any directory — no venv to 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 activate. Dependencies (PyMuPDF, PySide6, OpenCV, numpy) are all wheels; nothing
needs a system package. needs a system package. LilyPond is optional and only enables re-engraving.
Then:
```
noteman-slicer edit my-song.pdf
```
## Documentation ## Documentation
| | | | | |
|---|---| |---|---|
| [docs/guide.md](docs/guide.md) | How to use it: install, cut a score, place markers, export a bundle. Start here if you just want to make one. |
| [CONTEXT.md](CONTEXT.md) | Glossary. What a slice, cut, discard, bundle and song scale actually mean here. Start here. | | [CONTEXT.md](CONTEXT.md) | Glossary. What a slice, cut, discard, bundle and song scale actually mean here. Start here. |
| [slicer-handoff.md](slicer-handoff.md) | The design: pipeline, geometry model, detection, bundle format, and what noteman has to change. | | [docs/spec.md](docs/spec.md) | The specification: pipeline, geometry model, detection, editor, bundle format, and what noteman has to change. |
| [docs/adr/0001](docs/adr/0001-slicer-owns-image-processing-bundle-is-the-only-channel.md) | Why the slicer owns all image processing and the bundle is the only channel. | | [docs/bundle-format.md](docs/bundle-format.md) | The Score Bundle Format — a standalone specification of the export format, independent of this tool. |
| [BACKLOG.md](BACKLOG.md) | Deliberately deferred, with the reasoning that got it deferred. |
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. |
| [ADR 0007](docs/adr/0007-a-project-is-spent-once-exported.md) | A project is spent once exported; reopening starts fresh. Reverses an earlier decision. |
docs/adr/0002-raster-only-svg-renderer-deferred.md
+64
View File
@@ -0,0 +1,64 @@
# Raster only in release 1; the SVG renderer is deferred
Vector PDFs are most of the newer corpus, and keeping them vector all the way to
the viewer was an early goal — sheet music is line art, and SVG stays crisp at any
tablet zoom. We measured it before building it, and decided to **rasterize vector
sources like everything else in release 1** and revisit the SVG renderer once
real songs have been cut.
## The measurement
One real vector song, 6 pages, 65 systems, rendered both ways:
| Approach | Total | vs WebP |
|---|---|---|
| WebP slices (600 DPI → 1920, ink→alpha, lossless) | 1.19 MB | 1× |
| SVG, naive `viewBox` + `clipPath` | 26.0 MB | 40× |
| SVG, `set_cropbox` per band | 26.5 MB | 41× |
| SVG, bounding-box cull + glyph subset | 3.09 MB | 2.6× |
- **The naive cut is unusable.** A `viewBox` + `clipPath` slice contains the
entire page's geometry and merely hides eleven-twelfths of it.
- **`set_cropbox` does not help.** MuPDF renders full page content regardless of
the crop, so there is no free version of the cull.
- **The cull works.** PyMuPDF emits a `<defs>` glyph table (111 KB of a 256 KB
page) referenced by `<use transform="matrix(...)">`, plus body `<path>`
elements. Filter both by y-extent, then keep only the glyphs the survivors
reference. Roughly 50 lines, 15× improvement.
## Why defer, given the cull works
**Not size.** At 3.1 MB vs 1.2 MB per song — 225 MB vs 87 MB across a 73-song
corpus — both are nothing on a homelab. The measurement killed the lazy
implementation, not the idea.
What defers it is risk and missing evidence:
- The cull is **heuristic parsing**: glyph extents bounded at baseline ±14pt,
path extents read from raw `d` coordinates. It is over-inclusive by design, so
it fails safe — but "fails safe" still means a slice quietly carrying a
neighbour's slur, or a hairline dropped because the y-window was wrong on some
publisher's output. That needs eyeballing per song, a QA loop the raster path
doesn't have.
- Rendering 65 complex SVGs in a scrolling column may be slower than 65 WebPs.
Unmeasured.
- **The deciding question is unanswerable from here**: does 1920px WebP actually
feel insufficient when pinch-zooming on a tablet? Cutting real songs answers
it; more measurement doesn't.
Vector PDFs are also the *clean* case for the raster path — deskew is a no-op,
detection works best, there are no scan artefacts — so rasterizing them is not a
degraded fallback.
## Consequences
- The geometry model stays **renderer-agnostic**, in normalised page coordinates,
so adding the SVG renderer later is an output stage rather than a redesign.
- ~~**Re-export from the project file** regenerates every song's bundle without
repeating human work, so songs cut before the SVG renderer exists are not
stranded.~~ **No longer true** — see
[ADR 0007](0007-a-project-is-spent-once-exported.md). A project is spent once
its song has been exported, so songs cut before the SVG renderer ships stay
WebP unless they are cut again by hand.
- noteman needs no SVG support (`image/svg+xml`, `.svg` content type, CSP header
on SVG responses) until the renderer ships.
docs/adr/0003-lossless-webp-with-levels-and-alpha-quantisation.md
+58
View File
@@ -0,0 +1,58 @@
# Lossless WebP, with levels and alpha quantised to 16 levels
Slice images are encoded as **lossless WebP**, with the levels adjustment applied
and the alpha channel quantised to 16 levels. About 7 KB per slice, ~450 KB for a
65-system song. Every lossy option and every alternative format measured
*larger* for this content, which is the opposite of the usual intuition — hence
this record.
## The measurement
20 slices of one real song, levels applied throughout, relative to plain lossless
WebP:
| | vs baseline | |
|---|---|---|
| **WebP lossless + alpha quantised to 16** | **68%** | chosen |
| AVIF q60 | 90% | lossy, for 10% |
| WebP lossless | 100% | baseline |
| WebP lossy q85 (alpha) | 107% | |
| AVIF q85 | 114% | |
| JXL lossless | 130–133% | |
| WebP lossy q85 (opaque ink-on-white) | 158% | |
| PNG grayscale + alpha | 165% | |
| AVIF lossless | 188% | |
Separately, before levels: applying levels alone takes 338 KB → 211 KB, a 38%
reduction.
## Four results that contradict an instinct
- **Lossy is bigger than lossless here.** Not a quality problem — the measured
difference between q85 and lossless is max 12/255, mean 0.33, i.e. invisible.
Lossy VP8 simply spends more bits on sharp black/white edges than VP8L's
palette and predictor transforms do, and notation is nothing but sharp edges.
The "q85 looks fine" intuition comes from photographs and inverts here.
- **AVIF and JXL both lose**, AVIF lossless by nearly 2×. Their lossless modes
are afterthoughts on photo codecs. WebP's VP8L is close to purpose-built for
flat two-tone line art — sheet music is the content type it is best at. JXL
additionally has no path forward in Chrome.
- **Alpha costs nothing.** Opaque ink-on-white and black-plus-alpha are within
0.1% at lossless, so paper-tint removal and future non-rectangular slices are
free.
- **Levels is the single biggest lever** — 38%, as a side effect of a control
that exists for quality reasons anyway. Pushing the white point below the
paper's luminance sets vast regions to exactly `alpha = 0`, which costs almost
nothing to encode.
Alpha quantisation to 16 levels is imperceptible: antialiased edges span 2–3 px
at 1920, and 16 steps across that is below notice. 8 levels starts to gamble on
thin strokes.
## Rejected as not worth it
- **Encoder effort tuning** — Pillow's `method=6` buys 3% and a dependency.
- **`alpha_quality=60`** — 24%, for less control than quantisation gives.
- **Grayscale WebP** — no such mode exists. It wouldn't help anyway: the RGB
channels are constant black and compress to nearly nothing, so alpha is the
entire payload.
docs/adr/0004-detection-proposes-the-human-disposes.md
+55
View File
@@ -0,0 +1,55 @@
# Detection proposes, the human disposes — there is no unattended mode
Every automatic result the slicer produces — skew angle, cut positions, source
type, staff height, ink bounds — is a **suggestion the user confirms or modifies**
before it is committed. There is no batch mode, no headless "slice this folder",
and no code path that writes a bundle without a human having looked at it.
This is a constraint on the tool's shape, not a UI preference, which is why it
gets an ADR: it deletes an entire phase of the original plan and it will look
like a missing feature to anyone who finds the detection code and wonders why it
isn't wired to a CLI.
## Why
The corpus is PDFs from a choir's distribution channel, and quality varies
wildly — clean vector engravings at one end, noisy scans with a previous owner's
pencil markings at the other. **Testing showed the detection algorithms produce
unusable slices on any source with speckles or otherwise poor quality.** Not
slightly-off slices: unusable ones.
But the same testing showed the suggestions land *close* on decent sources —
close enough that correcting them is faster than placing cuts from scratch. So
detection earns its place as an accelerator, and loses any claim to being
load-bearing.
## What this rejected
The original plan's **Phase A** was a deliberately non-interactive CLI:
rasterize, auto-deskew, auto-detect boundaries, write numbered slices, and fix
the misses by hand in GIMP. Its justification was "learn the failure modes before
designing the editor," which is a good idea.
It doesn't survive the premise. A CLI whose output can't be trusted has GIMP as
its repair path — routing work back into the manual process the project exists to
remove. A diagnostic variant (dump per-page PNGs with proposed cuts drawn in red)
was considered and also dropped: it only re-shows a failure already confirmed by
testing, and the editor shows the same thing live.
Release 1 is therefore the editor and detection together. There is no smaller
first release that is actually usable.
## Consequences
- **Manual placement is the primary interaction**, not a correction affordance.
The editor must be fully usable with detection producing nothing.
- **Despeckling targets the detector, not the output.** The known failure mode is
specks, so a median blur and a small-component filter clean the row-darkness
profile the detector reads; the shipped pixels come from the levels-adjusted
image.
- Cut placement is deliberately **forgiving** — anywhere in the whitespace gap
yields the same output, since trim crops to ink afterwards. Precision is not
asked of the human.
- The editor should surface **slice edges**, not just cut lines, so trim
anomalies (a speck anchoring the bounding box) are visible rather than
discovered later in the viewer.
docs/adr/0005-pymupdf-for-all-pdf-access.md
+36
View File
@@ -0,0 +1,36 @@
# PyMuPDF for all PDF access, accepting AGPL
All PDF work — rasterizing at a chosen DPI, exporting SVG, and inspecting page
content to classify a source as bitmap or vector — goes through **PyMuPDF**. It
is a single wheel with MuPDF bundled, so the tool needs no system packages. Its
licence is **AGPL-3.0**, which we accept.
## Why not the permissive combination
The obvious permissive stack was `pypdfium2` (Apache/BSD) for rasterizing plus
`mutool` or `pdftocairo` shelled out for SVG. Both of those are **system
packages** — `mupdf-tools`, `poppler` — and a system package on the vector path
is precisely the failure the language choice was made to avoid: the tool is
supposed to install once and run from any directory on any machine.
The SVG step can't simply be skipped, either. Music glyphs come from a notation
font (Emmentaler, Bravura, or Sibelius/Finale's). An SVG that *references* a font
renders as garbage on a device that lacks it, so text must be converted to paths
at export. PyMuPDF does this **by default** — `page.get_svg_image(text_as_path=1)`,
verified to emit `<path>` elements and zero `<text>` — so the font risk is closed
with no extra tooling.
Mixing the two (pypdfium2 for raster, PyMuPDF only for SVG) is the worst option:
two libraries with overlapping responsibilities, and AGPL linked in anyway.
## Consequences
- **The AGPL propagates only if the slicer is published.** For a local personal
tool it costs nothing. A future permissive release would need the rasterizer
swapped back to `pypdfium2` — a contained change, since PDF access sits behind
the renderer-agnostic geometry model.
- **Source-type detection comes free** from the same library: `get_images()` plus
a full-page-image area check distinguishes a scan from an engraving.
- The SVG export path is present and working even though the SVG *renderer* is
deferred — see
[ADR 0002](0002-raster-only-svg-renderer-deferred.md).
docs/adr/0006-systems-are-found-by-brackets-not-row-gaps.md
+67
View File
@@ -0,0 +1,67 @@
# Systems are found by vertical brackets, not by row-darkness gaps
System detection anchors on the **vertical bracket / barline** that spans a
system's staves, and uses the row-darkness profile only to expand each anchor to
its ink extent. The obvious approach — find gaps in the row-darkness profile and
cut in the middle of them — does not work on multi-voice choral scores, which is
most of the corpus.
## Why the obvious approach fails
A row-darkness profile cannot distinguish an **inter-staff** gap from an
**inter-system** gap. In a 6-voice closed score, one system is six staves joined
by a bracket, and the gaps between those six staves look exactly like the gap
between two systems — only smaller, and not reliably so.
Measured on *Ketun joululaulu*, a 12-page 6-voice arrangement and the hardest
score in the repertoire:
- On page 2's first system, staff gaps run ~47px against a ~211px system gap. A
merge threshold tuned there works.
- On the same page's second system the lyrics fill the inter-staff gaps, so the
ratios invert and the same threshold merges the wrong things.
Result across all 12 pages, row-profile-only versus bracket-anchored:
| | bracket-anchored | row-profile only |
|---|---|---|
| systems per page | 2, 2, 2, 2, 2, 2, 3, 2, 2, 2, 2, 1 | 10, 6, 7, 7, 7, 8, 8, 5, 4, 5, 8, 4 |
The bracket-anchored counts match the score. The row-profile counts are wrong on
every page, and wrong by a different amount each time — so no threshold fixes
them.
## The algorithm
1. **Deskew per page.** Projection-profile variance sweep over ±5°. Measured skew
on this song ranges −2.6° to +1.2° *between pages of the same PDF*, so per-page
is not optional.
2. **Find anchors.** Binarise, then morphological open with a tall thin kernel
(height ≈ 3% of the page) so only long vertical strokes survive. Take
connected components taller than 4% of the page; walk them tallest-first,
keeping each one whose y-extent doesn't overlap an already-kept anchor. Each
surviving stroke is one system.
3. **Expand to ink.** Compute the row-darkness profile on a despeckled copy, take
its ink runs, and assign each run to the nearest anchor by centre distance. A
system's extent is the union of its runs.
4. **Place cuts** at the midpoint between consecutive systems' ink extents.
Step 3 is what makes this work rather than the bracket alone: a bracket stops at
the last staff line, but the slice must include the **lyrics below it**. On page
2, system 1's bracket spans 177–994 while its true ink extent is 179–1071 — the
77px difference is the bottom voice's lyric line, which the bracket misses
entirely and the row profile finds.
## Consequences
- Detection needs both signals. Neither the column pass nor the row pass is
sufficient alone, so `detect.py` computes both.
- **Scores without brackets** — single-staff melodies, lead sheets — have no
anchors, and fall back to row-profile runs. That fallback is the *only* correct
behaviour there, since every ink run genuinely is its own system.
- Bar numbers printed above a system (this score uses 11, 16, …) sit in their own
ink run and get absorbed into the nearest system by step 3. That is right: they
belong to the system they label.
- A page number can be absorbed the same way if its darkness clears the profile
threshold, inflating the last system's extent. The content rectangle and the
bottom discard slice both prevent this; don't rely on the threshold.
docs/adr/0007-a-project-is-spent-once-exported.md
+45
View File
@@ -0,0 +1,45 @@
# A project is spent once its song has been exported
Exporting a song marks its project file spent. Opening the PDF again starts a
**fresh session from detection** — no cuts, no discards, no metadata carried
over — rather than resuming. `--resume` on `edit`, `export` and `project`
overrides it when the old state really is wanted.
This **reverses an earlier decision**, which is the reason it needs recording:
the project file was introduced specifically so that state would persist, and
`docs/spec.md` and `CONTEXT.md` promised resume-across-sessions and re-export
until this ADR was written.
## What was decided before, and why it changed
The project file was chosen over "bundle only" for three benefits: crash safety,
resume across sessions, and re-export. The third was the strongest argument —
change the width cap, fix one cut, or add the SVG renderer later, and every
song's bundle regenerates without repeating any human work. ADR 0002 leans on it
explicitly when deferring the SVG renderer: "re-export from the project file
regenerates every song's bundle without repeating human work, so songs cut
before the SVG renderer exists are not stranded."
In use, persistence was the wrong default. Re-opening an exported song silently
resurrected old decisions, so a deliberate re-cut began from stale state instead
of a clean page — and because autosave writes that state straight back, closing
the window did not clear it either. An export is a natural end of a unit of
work; carrying its decisions past that point makes "start over" impossible to
express.
Crash safety and resume within a session are untouched, and those are what the
day-to-day authoring loop actually depends on: a session interrupted halfway
through a 12-page scan still picks up where it stopped.
## Consequences
- **Re-export is no longer free.** Changing the 1920px cap, changing the encoder,
or adding the SVG renderer means re-cutting each song by hand. ADR 0002's
"not stranded" reasoning no longer holds; if the SVG renderer ships, already
exported songs stay WebP unless they are cut again.
- The flag is written in `bundle.write`, not in its callers, so no export path
can forget it.
- The project file is kept rather than deleted, so `--resume` remains possible
and the state is still there to inspect after the fact.
- A CLI export from a PDF with no project file now writes one, marked spent.
That is the record that this PDF has already been exported.
docs/bundle-format.md
+448
View File
@@ -0,0 +1,448 @@
# Score Bundle Format, version 1
A container for one musical score, prepared for continuous-scroll display.
A bundle holds the score as a sequence of images — one per system of music —
together with the metadata that names the piece and the markers that describe
how a performer navigates it. It is self-contained: nothing outside the file is
needed to present the score.
This document defines the format. It does not describe any particular program
that writes or reads one.
## Terminology
**Slice** — one *system* of music: a single line spanning all voices, typically
four to twelve bars, with lyrics intact. A slice is the atomic unit of the
format. A slice is presented as an image; a slice that was engraved rather than
scanned may also carry the notation it was engraved from.
**Marker** — a semantic annotation attached to a slice, describing a navigational
feature printed in the score: a rehearsal letter, a repeat, a jump.
**Producer** — anything that writes a bundle. **Consumer** — anything that reads
one.
## Container
A bundle is a ZIP archive.
```
<name>.zip
├── song.json manifest: metadata, slice order, markers
├── original.pdf the source document (optional)
├── 001.webp
├── 002.webp
└── … one file per slice
```
- `song.json` is required and must be at the archive root.
- Slice images are at the archive root. Their names are given in `song.json`;
the zero-padded numbering shown is conventional, not required.
- `original.pdf` is optional. When present it is the document the score was
prepared from, carried along for printing or archival. It is not required to
present the score and consumers may ignore it.
- No directories, and no entries beyond those referenced by the manifest plus
the optional PDF.
- Compression method is unconstrained. Producers typically deflate `song.json`
and store the images and PDF, which are already compressed.
For scale: a twelve-page, twenty-four-slice choral score runs about 2.4 MB, of
which roughly 830 KB is the source PDF and the rest slice images at ~20 KB each.
## Manifest
`song.json` is UTF-8 encoded JSON.
```json
{
"v": 1,
"title": "Ketun joululaulu",
"composer": "trad.",
"arranger": "P. Rapi",
"tempo": 92,
"slices": [
{
"file": "001.webp",
"markers": [
{ "type": "rehearsal_letter", "label": "A" }
]
},
{
"file": "002.webp",
"markers": [
{ "type": "segno" },
{ "type": "to_coda", "destination": 7 }
]
},
{ "file": "003.webp" }
]
}
```
### Top-level fields
| Field | Type | | |
|---|---|---|---|
| `v` | integer | required | Format version. `1` for this document. |
| `slices` | array | required | Ordered, at least one entry. See below. |
| `title` | string | required | The name of the piece. |
| `subtitle` | string | optional | Alternate or translated title. |
| `composer` | string | optional | Who wrote the music. |
| `original_artist` | string | optional | Who originally performed the work, where that differs from the composer. |
| `arranger` | string | optional | Who adapted it for these forces. |
| `lyricist` | string | optional | Who wrote the words. |
| `translator` | string | optional | Who translated the words. |
| `tempo` | integer | optional | Beats per minute. |
| `voices` | string | optional | The parts in this arrangement, as free text. |
| `source` | object | optional | How the slices were cut from the archived document. See [Source geometry](#source-geometry). |
**Optional fields are omitted when they have no value.** A consumer will not
encounter an empty string or a null in place of an absent field.
`tempo` is a number, never a word: a figure can drive a metronome or a click
track, and verbal markings are not interchangeable between readers.
Unrecognised top-level fields may be added by future versions. A consumer should
ignore fields it does not know rather than reject the bundle.
### Slices
Each entry of `slices` is an object:
| Field | Type | | |
|---|---|---|---|
| `file` | string | required | Name of the image entry in the archive. |
| `page` | integer | optional | Index into `source.pages` — the page this slice was cut from. Present whenever `source` is. |
| `slot` | integer | optional | Which slice of that page this is, counting from 0 between its cuts. Present whenever `source` is. |
| `bar` | integer | optional | The measure this slice starts at, as numbered in the score. Omitted when unknown. |
| `markers` | array | optional | Markers on this slice. Omitted when there are none. |
| `engraving` | object | optional | The notation this slice's image was engraved from, when it was engraved rather than scanned. See [Engraving](#engraving). |
**The array order is the reading order of the score.** It is the only ordering
the format defines. Filenames often sort into the same order, but a consumer
must not derive order from them.
A slice's **index** is its zero-based position in this array. Indices are the
only identifiers the format has, and they are meaningful only within one bundle.
`bar` is the score's own numbering, not the format's: it says which measure this
system begins at, so a consumer can answer "take it from bar 33" by scrolling to
the right slice. It is independent of `index`, may be absent on any slice, and
carries no promise of being consecutive — a score numbers the systems it chooses
to, and pickup bars, repeats and voltas all break arithmetic on it.
## Slice images
Every slice image in a bundle satisfies the following. A consumer can rely on
these and does not need to inspect the images to lay them out.
- **Format: WebP, losslessly encoded.** (Lossless rather than lossy because
engraved music is line art — large flat areas separated by thin high-contrast
strokes — which lossless encoders compress *better* than lossy ones as well as
exactly.)
- **RGBA, with all three colour channels zero.** The image is carried entirely
by the alpha channel: ink is opaque black, paper is fully transparent, and
antialiased edges are partially transparent. Compositing a slice over a
background of any colour reproduces the printed appearance on that colour of
paper.
- **Uniform width within a bundle.** Every slice has the same pixel width, so a
consumer can lay them out in a single column without measuring. Systems
shorter than the widest are padded on the right with transparent pixels; they
end early rather than stretching.
- **Width is at most 1920 pixels**, and is frequently less. A narrower bundle is
not a defect: images are never enlarged beyond the resolution of their source,
because that adds bytes and softness without adding detail. Consumers should
scale to fit their own layout and should not treat 1920 as a target.
- **Height varies per slice**, being the height of that system.
- **Slices need not be rectangular in content.** Where two systems interleave —
for example a section label printed level with the previous system's lyric
line — the boundary between them steps, and each slice is delivered as its
bounding box with the region belonging to its neighbour left transparent. This
requires nothing special from a consumer; it composites correctly.
Images are **presentation-ready**. They have already been deskewed, cropped,
levelled and scaled as a set. Re-encoding, re-cropping or re-scaling them
individually will at best waste work and at worst break the uniformity the
format guarantees.
One specific hazard is worth naming, because it is silent: an image pipeline
that *discards* the alpha channel rather than compositing it will turn every
slice into a solid black rectangle, since the colour channels are all zero.
## Source geometry
A bundle can say how its slices were cut, in a `source` object. With it a
consumer can reopen the score for editing; without it the bundle is a one-way
trip, since the slice images are output and the decisions that produced them
would live only in whatever tool made them.
```json
"source": {
"file": "original.pdf",
"pages": [
{
"skew": -0.4,
"content": [0.083, 0.0, 0.947, 1.0],
"levels": [46, 173],
"cuts": [
[[0.0, 0.0449], [1.0, 0.0449]],
[[0.0, 0.3662], [0.35, 0.3662], [0.35, 0.3901], [1.0, 0.3901]]
]
}
]
}
```
| Field | Type | | |
|---|---|---|---|
| `file` | string | required | The archive entry the slices were cut from. `"original.pdf"` in practice. |
| `pages` | array | required | One entry per page of that document, in its own page order. |
Each entry of `pages`:
| Field | Type | | |
|---|---|---|---|
| `cuts` | array | required | The boundaries between slices, ordered top to bottom. May be empty: a page with no cuts is one slice. |
| `skew` | number | optional | Degrees the page was rotated by before cutting. Default `0`. |
| `content` | array | optional | `[x0, y0, x1, y1]` — the part of the page that is music. Default the whole page. |
| `levels` | array | optional | `[black, white]` — the black and white points applied. Default `[0, 255]`. |
**Everything here is in normalised page coordinates**, `0.0` to `1.0` on each
axis, origin top-left. Nothing is in pixels, so the geometry holds however the
document is rendered and at whatever resolution.
A **cut** is a polyline: a list of `[x, y]` points, left to right. Two points is
a straight cut; more steps around a system that interleaves with its neighbour —
a section label printed level with the previous system's lyrics. A slice's top
boundary is the cut above it and its bottom boundary the cut below it, with the
page edge standing in at either end.
A page with *n* cuts therefore has *n + 1* **slots**, numbered from 0 downward.
Each slice names the `page` and `slot` it came from. **A slot that no slice
claims was discarded** — a page header, a footer, a title block. That is stated
by omission rather than directly, because shipping a discarded slice's image
would defeat discarding it.
The archived document is the source of truth for reopening: the slice images are
output, and a consumer that reopens a bundle re-renders them rather than
importing them.
`source` is optional, so a bundle without one is still valid — it is simply not
reopenable, and a consumer should say so rather than pretend otherwise. What it
can still recover from such a bundle is the title block, and, if it cuts the
document again and happens to find exactly as many slices, the markers: the
slices array is in reading order, so it lines up with any other list in reading
order. One slice more or fewer and it does not, which is why that is a fallback
and not the design.
## Engraving
Most slices are photographs of print: an image and nothing more. A slice that
was *engraved* — set from notation rather than scanned — can carry the notation
it came from, in an `engraving` object.
```json
{
"file": "007.webp",
"bar": 33,
"engraving": {
"lang": "lilypond",
"key": "aes",
"time": "4/4",
"print_time": false,
"voices": [
{ "clef": "treble", "notes": "c4 des ees f | ees2. r4", "lyrics": "Kai -- paa -- va sy -- dän" },
{ "clef": "treble_8", "notes": "aes,4 aes aes aes | aes2. r4" },
{ "clef": "bass", "notes": "aes,4 ges f ees | aes2. r4" }
]
}
}
```
| Field | Type | | |
|---|---|---|---|
| `lang` | string | required | The notation language. `"lilypond"` is the only value defined by this version. |
| `voices` | array | required | One entry per staff, in the order they are printed top to bottom. At least one. |
| `key` | string | optional | Key signature, in `lang`'s spelling. For `lilypond`, the tonic of the major spelling: `"aes"`, `"c"`, `"fis"`. |
| `time` | string | optional | Time signature, as `"4/4"`. |
| `print_time` | boolean | optional | Whether the time signature is printed on this system. Default `false`. |
Each entry of `voices`:
| Field | Type | | |
|---|---|---|---|
| `notes` | string | required | The music for this staff, verbatim in `lang`. |
| `clef` | string | optional | `"treble"`, `"treble_8"`, `"alto"`, `"bass"`. Default `"treble"`. |
| `lyrics` | string | optional | The words under this staff, verbatim in `lang`. Omitted when the staff has none. |
Three properties make this worth carrying:
- **It is the source, not a transcription.** The image was engraved from exactly
these strings. A consumer that re-engraves them gets the same system back.
- **It is editable.** A wrong note can be corrected here and the slice engraved
again, which a raster image does not allow.
- **It is playable.** `voices` are separated per staff with pitches, durations
and a key, so the passage can be sounded — a practice track, a click, a
pitch reference — without anyone reading the image.
`notes` and `lyrics` are opaque to this format. They are whatever `lang` accepts,
including constructs the fields above say nothing about: slurs, dynamics,
tuplets, and the tie idioms that carry a note across a slice boundary. A consumer
that does not speak `lang` must pass them through unaltered or ignore them, never
attempt to repair them.
An `engraving` **describes the slice above it, not the whole song**. Each is
self-contained: `key` and `time` are stated per slice, so nothing has to be
inherited from a neighbour or from the bundle. Slices without an `engraving` are
scanned, and the two kinds mix freely within one score — re-engraving a single
ruined system is the ordinary case.
A consumer that only presents the score can ignore `engraving` entirely. The
image is always the authority on what the slice looks like; where an image and
its engraving disagree, the image is what the producer intended to be read.
Notation languages other than `lilypond` may be added by future versions. A
consumer should ignore an `engraving` whose `lang` it does not know, and present
the slice image as it would any other.
## Markers
A marker annotates the slice it appears on.
| Field | Type | | |
|---|---|---|---|
| `type` | string | required | One of the vocabulary below. |
| `label` | string | optional | Free text. Meaningful for `rehearsal_letter`, `section_label` and `volta`. |
| `destination` | integer | optional | Index into `slices`. Present on jump types. |
A slice may carry several markers. Their order within the array is not
significant.
### Vocabulary
Named positions — places a performer may be directed to:
| `type` | Meaning |
|---|---|
| `rehearsal_letter` | A boxed letter or number printed above a system, used to say "from C". `label` holds it. |
| `section_label` | A named section: INTRO, VERSE, CHORUS. `label` holds the name. |
| `segno` | The 𝄋 sign, target of a *dal segno*. |
| `coda` | The 𝄌 sign, beginning of the closing section. |
| `fine` | The end of the piece when reached by a *da capo* or *dal segno*. |
Structural notation — printed context, affecting how the music is read but not
directing the reader elsewhere:
| `type` | Meaning |
|---|---|
| `repeat_start` | The start of a repeated passage. |
| `repeat_end` | The end of a repeated passage. |
| `volta` | An alternative ending bracket. `label` holds its number. |
Jumps — points where the reader is directed to another slice:
| `type` | Meaning |
|---|---|
| `to_coda` | "To Coda": leave here for the coda. |
| `ds_al_coda` | *Dal segno al coda*: return to the segno. |
| `ds_al_fine` | *Dal segno al fine*: return to the segno and play to the fine. |
| `dc_al_coda` | *Da capo al coda*: return to the beginning. |
| `dc_al_fine` | *Da capo al fine*: return to the beginning and play to the fine. |
| `generic_jump` | An unclassified jump. |
**Every jump marker states its destination explicitly**, as an index into
`slices`. A consumer does not need to infer where a jump leads by searching for
a matching `coda` or `segno`, and must not assume a bundle contains only one of
each. A `destination` always refers to an existing index.
Unrecognised marker types may be added by future versions. A consumer should
ignore markers it does not understand rather than reject the bundle.
## Versioning
`v` is an integer that increases when a change would break an existing consumer.
Additions that a consumer can safely ignore — new optional fields, new marker
types, new `engraving` languages — do not increase it. `engraving` and `source`
were both added this way: a bundle carrying them is still a version 1 bundle,
and a consumer that has never heard of them presents the score unchanged.
A consumer should refuse a bundle whose `v` it does not recognise rather than
attempt to interpret it.
## Validating a bundle
A consumer is advised to check:
- `v` is a recognised version.
- `title` is present and non-empty; `slices` is a non-empty array.
- Every `file` names an entry present in the archive.
- Every `destination` is within the bounds of `slices`.
- Every `engraving` has a `lang` and a non-empty `voices`; unknown `lang` values
are ignored rather than rejected.
- If `source` is present: its `file` names an entry in the archive, every slice
carries a `page` within `source.pages` and a `slot` within that page's slot
count, and no two slices claim the same one.
- Archive entry names contain no path separators, no `..`, and no absolute
paths, as with any archive from an untrusted source.
## Identity and updates
A bundle describes one complete score. The format has no notion of updating a
previously read bundle: there are no stable identifiers, and a slice's index is
meaningful only within the bundle that contains it.
Reopening a bundle for editing, via [`source`](#source-geometry), does not change
that. What comes out is a new document that happens to have been derived from an
old one, not a revision of it.
Two bundles of the same piece are therefore independent documents, not versions
of one. A consumer that stores imported bundles and assigns its own identifiers
should treat a second bundle as a new score rather than merging it into an
existing one — jump destinations resolved against the first bundle's slices do
not survive being repointed at a second bundle's.
## Complete example
A 24-slice bundle, abbreviated:
```
song.zip
├── song.json 1.4 KB
├── original.pdf 827 KB
├── 001.webp 21 KB 1489 × 1058
├── 002.webp 18 KB 1489 × 818
├── …
└── 024.webp 1489 px wide, like every other slice
```
```json
{
"v": 1,
"title": "Ketun joululaulu",
"composer": "trad.",
"arranger": "P. Rapi",
"tempo": 92,
"slices": [
{ "file": "001.webp", "markers": [ { "type": "rehearsal_letter", "label": "A" } ] },
{ "file": "002.webp", "markers": [ { "type": "segno" },
{ "type": "to_coda", "destination": 7 } ] },
{ "file": "003.webp" },
{ "file": "004.webp" },
{ "file": "005.webp" },
{ "file": "006.webp" },
{ "file": "007.webp", "engraving": { "lang": "lilypond", "key": "aes", "time": "4/4",
"voices": [ { "clef": "treble",
"notes": "c4 des ees f | ees2. r4",
"lyrics": "Kai -- paa -- va sy -- dän" },
{ "clef": "bass",
"notes": "aes,4 ges f ees | aes2. r4" } ] } },
{ "file": "008.webp", "markers": [ { "type": "coda" } ] },
{ "file": "009.webp" }
]
}
```
Reading the score means presenting `001.webp` through `024.webp` in that order,
in one column, each scaled to the same width. A reader who follows the `to_coda`
on slice index 1 continues at slice index 7.
docs/guide.md
+187
View File
@@ -0,0 +1,187 @@
# Making a bundle
Start to finish: a score PDF in, one `.zip` out that noteman can open. Fifteen
minutes for a typical four-page song, most of it spent nudging cuts.
## Install
```
uv tool install --editable .
```
That puts `noteman-slicer` on PATH; it runs from any directory. Everything it
needs is a wheel — no system packages. LilyPond is optional and only enables
re-engraving (below); without it the tool works the same minus that pane.
## The one command you need
```
noteman-slicer edit my-song.pdf
```
The editor opens on page 1 with detection's guesses already drawn: horizontal
**cuts** between the systems, a **skew** correction, and a blue **content
rectangle** marking what is music rather than page margin. All of it is a
starting point — detection is an accelerator, not an authority. Fix whatever is
wrong.
Your work is saved to `my-song.slicer.json` next to the PDF, automatically on
export and with Ctrl+S any time. Closing and reopening picks up where you left
off.
## What you do on each page
1. **Straighten it.** If the staff lines slope, turn the *Skew* dial until they
are level. The preview updates live.
2. **Fix the cuts.** One cut line per boundary between systems. Double-click to
add one, drag to move it, right-click to delete it. A cut is a polyline, not
a straight line — Ctrl-click on a cut adds a vertex, so it can bend around a
low-hanging lyric or a slur that crosses the gap. Right-click a vertex to
drop it.
3. **Discard what isn't music.** Page headers, footers, page numbers and title
blocks are slices too, and they should not reach the tablet. Click the slice,
press <kbd>D</kbd>. Discarded slices show hatched. <kbd>D</kbd> again brings
one back.
4. **Set the content rectangle.** Drag the blue edges so they hold the music and
nothing else. This is the horizontal crop for every slice on the page.
5. **Check black and white points.** Under *Page* is the scan's own histogram:
a hump of ink on the left, a hump of paper on the right, and two handles you
drag. Put the white handle at the foot of the paper hump and the black one at
the foot of the ink hump. The strip underneath shows the tone that results.
Getting this wrong is the one mistake you cannot see until the bundle is on
the tablet — grey ink becomes half-transparent ink, and nothing downstream
can rescue it. Arrow keys nudge the black point, Shift+arrows the white one.
The page rail across the top of the panel has one chip per page, with the number
of slices on it underneath. Click to go there, or use Page Up / Page Down. A page
whose count is far off its neighbours' is usually a page where detection missed
a system. Levels carry over from the previous page, so a consistent scan only
needs setting once.
## Bar numbers
Under *This slice*, **First bar** is the measure that slice starts at, as the
score numbers it. Optional, and only worth filling in where the printed score
shows a number — that is what lets noteman answer "take it from bar 33". A
re-engraved slice prints the number above its first bar, exactly as the scanned
systems around it do.
## Markers
Markers are the navigation symbols noteman uses to jump around the score:
rehearsal letters, section labels, segno, coda, fine, repeats, voltas, and the
D.S./D.C. instructions. They belong to a slice.
Select the slice, pick the type, type a label if the type takes one (rehearsal
letters, section labels and voltas do), and press **Add**.
Jump markers — *to coda*, *D.S. al coda*, *D.C. al fine* and friends — also need
a destination. After adding one, press **Set target…** and click the slice it
jumps to, on any page. That is what lets noteman follow the repeat structure
instead of just scrolling.
## The title block
Fill in the *Song* section. **Title is required** — export refuses without one.
The rest (subtitle, composer, original artist, arranger, lyricist, translator,
voices) is optional and travels with the bundle into noteman's library.
*Tempo* is beats per minute, a number, because a number can drive a metronome
and "Andante" cannot.
## Export
**Export bundle…**, choose where the `.zip` goes, done. It is named after the
song's title — *Bicycle Race* becomes `Bicycle-Race.zip`. Inside are the slice
images in order, their markers, the song metadata, and the original PDF as the
archive copy. That zip is the whole interface to noteman; hand it over and open
it there.
Two things worth knowing:
- **Shrink the original PDF…** offers to store the archived PDF as bilevel,
which is dramatically smaller for scans. It shows you a before/after crop
first — check that the staff lines survived. It never touches the slices.
- **An exported project is spent.** Reopening the same PDF starts fresh from
detection rather than resuming decisions that already shipped. If you really
want the old cuts back, `noteman-slicer edit my-song.pdf --resume`.
## Reopening a bundle
```
noteman-slicer open my-song.zip
```
Unpacks the archived PDF beside the bundle, rebuilds the project from it — the
cuts, skew, levels, discards, markers, title block and any re-engraved systems —
and opens the editor on it. Everything you changed re-renders from the PDF; the
slice images in the zip are output and are thrown away.
This works on any bundle, not just one you made: the cuts travel in `song.json`.
It refuses to overwrite a PDF or project file that is already there, since the
obvious place to unpack is exactly where someone's unfinished work lives — pass
`--pdf elsewhere.pdf` or `--force` if you mean it.
A bundle from a producer that does not record its cuts can still be opened, but
it is a fresh session rather than a round trip: it asks first, then cuts the PDF
from scratch with detection. The title block always comes back. Markers and
re-engraved systems land only if detection happens to find exactly as many
slices as the bundle has — the slices are in reading order on both sides, so
they can be lined up, but one system found or missed would shift every marker
onto the wrong slice, so in that case they are left off entirely and it says so.
`--detect` answers the question in advance, for scripts.
## Re-engraving a slice (optional, needs LilyPond)
When a system is beyond rescue — a bad scan, a wrong transposition, a passage
you want rewritten — shift-double-click it. A window opens where you enter the
music as LilyPond, one block per voice, render, and compare against the
original. Accept and the rendered version replaces that slice in the bundle.
The LilyPond you typed travels in the bundle alongside the image, so the passage
can be corrected and re-engraved later, or played, without the project file.
## Mouse and keyboard
| | |
|---|---|
| Double-click | add a cut |
| Drag a cut | move it |
| Ctrl-click a cut | add a vertex |
| Right-click | delete the cut or vertex under the cursor |
| Click a slice, then <kbd>D</kbd> | discard it (or bring it back) |
| Drag the blue edges | resize the content rectangle |
| Shift-double-click a slice | re-engrave it |
| <kbd>Page Up</kbd> / <kbd>Page Down</kbd> | previous / next page |
| <kbd>Ctrl</kbd>+<kbd>S</kbd> | save the project |
## What the tool won't do
Erasing a previous owner's pencil marks, chord letters and breath marks. Do that
in GIMP before slicing — with a stylus it is quick, and no amount of thresholding
substitutes for it.
## When something looks wrong
| | |
|---|---|
| Detection found no systems, or one giant one | The score has no bracket joining the staves; add the cuts by hand. |
| "The PDF has changed since these cuts were made" | The file was edited or replaced under an existing project. The cuts probably no longer line up — re-cut. |
| Export says a title is required | Fill in *Song → Title*. |
| Slices look grey and washed out | The white point is too high — drag it down onto the paper hump. |
| Notes have holes in them | The black point is too high — drag it left, off the ink hump. |
## The command line
The editor is the tool; these exist for checking things quickly.
```
noteman-slicer info my-song.pdf # source type and page rasters
noteman-slicer detect my-song.pdf # detection results + debug overlays
noteman-slicer project my-song.pdf # what the project file currently holds
noteman-slicer export my-song.pdf # export without opening the editor
noteman-slicer open my-song.zip # unpack a bundle; --no-edit to stop there
```
Every command that takes a PDF takes `--type raster|vector` to override
source-type detection.
docs/spec.md
+446
View File
@@ -0,0 +1,446 @@
# noteman-slicer — specification
What the tool does and how it behaves. Vocabulary is in
[`CONTEXT.md`](../CONTEXT.md); the reasoning behind the expensive decisions is in
[`docs/adr/`](adr/).
## Scope
A local, single-user tool that turns a score PDF into the ordered slice images
[noteman](../../noteman) consumes, plus the navigation markers that sit on them.
It automates the mechanical part of noteman's ingestion boundary.
It is **not** a GIMP replacement. Erasing previous-owner pencil marks, chord
letters and breath marks stays in GIMP — the irreducible manual part, which GIMP
with a stylus already does well.
**One PDF → one song → one project → one bundle.** Never a many-to-one in any
direction. A PDF is either bitmap or vector, never mixed.
### Why it's separate from noteman
Splitting it out removed the double-implementation constraint — in-app, every
operation needs both a fast browser preview and a real server-side render, and
that constraint is what priced dewarp and brush masking out entirely, not the
algorithms. It also removed infrastructure noteman doesn't otherwise need (a
scratch workspace for multi-MB rasters, an edit-list table, cleanup sweeps for
orphaned temp files, poppler in the Docker image, an admin UI surface), and
unlocked real image libraries.
It costs nothing: song creation is admin-only, done at home, once per song.
## Operating principle
**Detection proposes, the human disposes.** Every automatic result — skew angle,
cut positions, source type, staff height, ink bounds — is a suggestion the user
confirms or modifies before it is committed. There is no unattended mode. See
[ADR 0004](adr/0004-detection-proposes-the-human-disposes.md).
## Geometry model
**One geometry model, two renderers.** Geometry is stored in **normalised page
coordinates** (0–1 of page width and height), independent of DPI and of which
renderer produces the output. Only the final stage differs.
| Concept | Raster | Vector |
|---|---|---|
| Cut | y in pixels | y in PDF user space |
| Discard | drop the slice | drop the slice |
| Content rectangle | crop before cutting | clip before cutting |
| Trim | crop to ink bbox | crop `viewBox` to ink bbox |
| Uniform width | transparent right pad | wider `viewBox`, same content |
| Staff-height normalise | scale factor | scale factor |
| Deskew, levels, ink→alpha, 1920 cap | yes | no |
Only the raster renderer ships in release 1 — see
[ADR 0002](adr/0002-raster-only-svg-renderer-deferred.md). The editor is one
editor regardless, since a vector PDF has to be rasterized just to display it on
screen.
### Pipeline order
```
load raster → deskew → levels → content rect → cut → discard
→ trim → scale → pad → ink→alpha → encode
```
**Load raster** differs by source type. A scanned PDF carries one full-page image
per page, and that image *is* the scan — extract it at its native resolution
(`extract_image`) rather than re-rendering the page. Re-rendering at a fixed
600 DPI resamples a 200 DPI scan up by 3×, which triples the pixel count and adds
no detail. A vector PDF has no embedded raster, so it is rendered — see the DPI
note in *Reference values*.
The rest of the order is not arbitrary:
- **Levels before anything geometric**, so the trim bounding box is computed on
the image that actually ships.
- **Content rect before cutting**, so margin junk never enters a slice.
- **Trim before scale**, since the scale factor derives from the widest *trimmed*
slice.
### Slices, cuts and discard
A page starts as a single slice; each cut splits one slice into two. Slices
therefore tile the page with no gaps and no overlap.
Headers, footers and blank regions leave the song via a **discard** flag, not via
cuts at the page edges. Modelling a slice as "the region between two cuts" leaks:
page 2 has no header, so it would need an invented top cut whose position depends
on whether that page happens to have one.
Cut placement is forgiving — anywhere inside the whitespace yields the same
output, because trim crops to ink afterwards.
**A cut is a polyline, not a line.** Two points — a straight horizontal
boundary — is the ordinary case and what detection proposes. Extra vertices exist
because publishers routinely print a section label in the left margin at the same
height as the *previous* system's lyrics. On page 1 of *Engel* (Bosse/Partitura
edition), the boxed `VERSE 1` label and the preceding system's bass lyric line
occupy the same rows: ink is present on both sides of the page throughout that
band, so no horizontal line separates them. `VERSE 1` belongs to system 2, the
lyrics to system 1. The cut has to step — above the label on the left, below the
lyrics on the right.
A slice bounded by a non-straight cut is **not rectangular**. Its image is the
bounding box of the region, with everything outside the region made transparent.
That composites invisibly on the viewer's sheet, so nothing downstream needs to
know. This is also why masking must paint transparency rather than white.
### Content rectangle
The region of a page that holds music, set per PDF and adjustable per page,
applied before cutting. Everything outside it is dropped.
This handles margin junk structurally rather than case-by-case, because margin
junk is by definition outside the music: scan-edge bands, spine shadows, and page
numbers printed in the side margin level with a system. That last one matters
more than it looks — see the trim consequences below.
### Trim, scale, pad
**Trim** tight on all four sides, per slice. This normalises away the left-margin
drift between scanned pages, and flattens the engraved indent of the first
system — correct here, since noteman strips the printed header the indent made
room for.
Two consequences:
- A stray speck at the far left anchors the trim, shifting that slice relative to
its neighbours. Mitigate by ignoring connected components under a few hundred
pixels (`cv2.connectedComponentsWithStats`) when computing the bounding box.
- A page number in the side margin level with a system would set that slice's
bounding box, which sets the song's widest slice, which scales the whole song
down. One artefact, whole song smaller. Hence the content rectangle.
**Scale is normalised on staff height, not width.** Width-based scaling assumes
every slice comes from the same scan at the same DPI. It breaks for a rescanned
page, a PDF mixing scan generations, or a re-engraved replacement system — whose
width depends on how much music is in it, not on matching its neighbours. Staff
height is the invariant a reader perceives as "the notes are the same size", and
it falls out of the same row-darkness profile detection already computes.
Two steps, both per song: normalise every slice to a common staff height, then
scale the song uniformly so its widest slice lands at **1920px**. That is a
ceiling, never a target — **never upscale**. A song that comes out narrower stays
narrower; enlarging a 600 DPI scan past its real resolution buys softness and
bytes and no detail.
**Pad** narrower slices with transparency on the right, so every slice in a song
is the same width, flush left, notes the same size. A short system simply ends
earlier.
### Encoding
**Lossless WebP, with levels applied and alpha quantised to 16 levels.** Roughly
7 KB per slice, about 450 KB for a 65-system song. Lossy encodings and the
alternative formats are all *larger* for this content — measured, with the
figures, in
[ADR 0003](adr/0003-lossless-webp-with-levels-and-alpha-quantisation.md).
Ink handling is luminance → alpha: ink forced to pure black,
`alpha = 255 − luminance`. Not `pixel == white` thresholding — staff lines are
antialiased, and binary removal leaves jagged edges.
## Detection
All of it is a suggestion, all of it overridable.
**Deskew** — per page, and not optionally so: measured skew varies from −2.6° to
+1.2° *between pages of the same PDF*. Staff lines are by far the strongest
horizontal signal in sheet music, so a projection-profile variance sweep over ±5°
finds the angle reliably — sum row-darkness for each candidate angle, take the
angle of maximum variance. Run on a downscaled copy. Pair with a manual slider.
**Systems** — anchored on the **vertical bracket** that spans a system's staves,
not on gaps in the row-darkness profile. A row profile cannot distinguish an
inter-staff gap from an inter-system gap on multi-voice choral scores, and gets
the system count wrong on every page. See
[ADR 0006](adr/0006-systems-are-found-by-brackets-not-row-gaps.md) for the
measurement and the full algorithm. In outline:
1. Binarise; morphological open with a tall thin kernel so only long vertical
strokes survive; keep non-overlapping components taller than 4% of the page.
Each is one system.
2. Take ink runs from the row-darkness profile and assign each to the nearest
anchor. A system's extent is the union of its runs — this is what pulls in the
lyrics printed *below* the last staff, which the bracket stops short of.
3. Propose cuts at the midpoint between consecutive systems' ink extents, and
pre-set the discard flag on a page's top and bottom slice when they contain no
system.
Scores with no bracket — single-staff melodies, lead sheets — have no anchors and
fall back to row-profile runs, which is correct there.
**Staff height** — peak-to-peak spacing in the row profile.
**Content rectangle** — proposed per page from the staff lines. Staff lines are
long *horizontal* runs, while a scan-edge shadow, a spine darkening and the
streak a dirty scanner glass leaves are all *vertical*, so opening with a wide
flat kernel keeps the music and erases the artefacts. Three details make it
work:
- Only rows inside detected systems are searched. Otherwise a horizontal scan
artefact above or below the music is itself a long horizontal run, and it
reaches the paper edge.
- The horizontal bounds come from a *percentile* of the staff-line extents, not
their maximum. Where an artefact touches the end of a staff line the two merge
into one component; a page has dozens of staff lines and only a few are
contaminated.
- The left bound also considers the **brackets**, which sit left of every staff
line. A bound taken from staff lines alone crops the bracket off, and a
bracket is notation.
Only the horizontal bounds are proposed. Vertically the cuts and discard flags
already isolate the header and footer, and cropping the top would risk clipping
a tempo mark or a section label above the first staff.
**Source type** — `get_images(full=True)` / `get_drawings()` proposes bitmap or
vector per PDF; the tool asks the user to confirm before routing. (`full=True` is
required, or `get_image_bbox` rejects the item.)
**Despeckle feeds detection only.** A median blur plus dropping tiny connected
components denoises the *profile the detector reads*; the shipped pixels come
from the levels-adjusted image. The known failure mode is specks, so the fix
belongs on the signal, not the output.
## Levels
Two sliders per song (black point, white point) applied via `cv2.LUT`, with a
per-page override.
In release 1, not deferred: with `alpha = 255 − luminance`, a scan's greyness
*becomes* transparency, so a faint or yellowed source produces washed-out notes
on a hazy background and **nothing downstream can rescue it**. Set the white
point just under the paper's luminance and the paper vanishes completely; set the
black point at the ink's darkest and notes go solid. It is also the single
biggest lever on output size.
**Detection proposes both**, like it proposes cuts and skew, because the default
0–255 is the one setting whose harm is invisible until the bundle is on a tablet.
Notation is two-tone, so Otsu's split between ink and paper is the measurement;
the points sit halfway from it to each end of the range, leaving the ramp between
them as the antialiasing. A page already scanned bilevel has no interior split —
Otsu degenerates to 0 there — and is left at 0–255. The proposal is per page and
the median becomes the song's, so a near-blank page cannot set it.
Adaptive methods (CLAHE, adaptive thresholding) are the trap — tuned for text,
they eat the thin stuff on notation: hairpin tips, slur ends, ledger lines,
tapered beams. A global LUT whose effect you can see beats a local algorithm you
can't predict.
## Editor
**PySide6.** `QGraphicsView` provides the viewport — pan, zoom, screen↔image
coordinate mapping, resampling, hit-testing — which would otherwise be ~150 lines
of hand-rolled geometry. `cv2.imshow` was rejected: OpenCV's highgui is GTK/X11
and lands on XWayland at best, and it has no text input at all.
What the editor does: pan and zoom the page, drag cut lines, toggle discard,
adjust the content rectangle, move the levels sliders, place markers, fill in
song metadata, export.
Marker placement needs a **slice picker** — a `QListView` in icon mode over the
slice previews — since every jump source stores an explicit target. One widget
serving all six jump types.
## Project file
Autosaved JSON beside the source PDF, holding the source path and hash, cuts,
discards, content rectangle, skew angles, levels, staff-height overrides, markers
and metadata. The bundle is *generated* from it, so export is a pure function of
the project file plus the PDF.
It buys crash safety and resume across sessions, since authoring is trickle-in:
a session interrupted halfway through a 12-page scan picks up exactly where it
stopped.
**A project is spent once its song has been exported.** Export records that in
the file, and opening the PDF again starts a *fresh session from detection*
rather than resuming. A re-cut therefore never inherits decisions that have
already shipped. `--resume` overrides it on the `edit`, `export` and `project`
commands when the old state really is wanted.
The cost is deliberate: re-export is no longer free. Changing the width cap or
adding the SVG renderer later means re-cutting each song by hand rather than
regenerating every bundle from its project file.
The project file references the PDF and never contains it; the hash lets the
editor warn if the PDF changed underneath.
## Markers
Placed here rather than in noteman: at cut time you are already reading the score
page by page at full resolution, so the Segno, the Coda sign, the "to coda" text
and the rehearsal letters are on screen. Deferring means reading the whole score a
second time to find the same symbols.
noteman's vocabulary, carried verbatim — `rehearsal_letter`, `section_label`,
`segno`, `coda`, `fine`, `repeat_start`, `repeat_end`, `volta`, `to_coda`,
`ds_al_coda`, `ds_al_fine`, `dc_al_coda`, `dc_al_fine`, `generic_jump`. A small
stable enum, but real coupling: adding a type means changing both repos.
Three shapes among them:
- **Bare tags:** `segno`, `coda`, `fine`, `repeat_start`, `repeat_end`.
- **Tags with free text:** `rehearsal_letter` ("C"), `section_label` ("CHORUS"),
`volta` ("1.").
- **Jump sources:** `to_coda`, `ds_al_coda`, `ds_al_fine`, `dc_al_coda`,
`dc_al_fine`, `generic_jump`.
**Every jump source stores its target slice explicitly.** noteman's viewer
currently resolves by type — a `to_coda` finds the song's unique `coda` at tap
time — but that puts an unwritten "exactly one Coda per song" invariant into a
contract between two separately-maintained repos, enforced by neither. Authoring
the target costs one click on a slice already on screen, and in exchange the
bundle is self-describing and a score with two codas simply works.
## Bundle
The only channel to noteman. No API, no direct upload — see
[ADR 0001](adr/0001-slicer-owns-image-processing-bundle-is-the-only-channel.md).
```
song.zip
song.json
original.pdf
001.webp 002.webp …
```
```json
{
"v": 1,
"title": "…", "composer": "…", "arranger": "…",
"slices": [
{ "file": "001.webp" },
{ "file": "002.webp", "markers": [{ "type": "rehearsal_letter", "label": "A" }] },
{ "file": "003.webp", "markers": [{ "type": "to_coda", "destination": 7 }] }
]
}
```
Array order **is** slice order — one ordering, not two. Markers nest inside the
slice they sit on, so indices appear in exactly one place: a jump source's
`destination`.
`"v": 1` is eight bytes of insurance. The bundle is the only channel, MIDI and
MP3s are planned for a later phase, and bundles are archived artifacts that may be
re-imported a year later.
The manifest also carries the cuts, in a `source` block: the polylines, skew,
levels and content rectangle per page, and the page and slot each slice came
from. That is what makes `noteman-slicer open song.zip` a real round trip rather
than a re-detection that happens to land nearby — it unpacks the archived PDF,
rebuilds the project from the geometry, and re-renders. The images in the zip
are output and are discarded on the way back in. Slots no slice claims were the
discarded ones; a bundle states that by omission, since shipping a discarded
slice's image would defeat discarding it.
Otherwise: plain zip, no manifest beyond this, no checksums, hand-fixable.
Python's `zipfile` is stdlib; the import side needs one zero-dep library
(`fflate`), since Bun has zlib but no zip reader.
**Contents:** slices, markers, the original PDF, and song-level metadata (title,
subtitle, composer, original artist, arranger, lyricist, translator, tempo,
voice list). Metadata is included not because the slicer transforms it but
because you have to read the title block anyway to mark the header slice
discarded — typing the fields while it's on screen beats reopening the PDF
later.
**Title is required**; everything else is optional and omitted when blank.
**Tempo is an integer**, beats per minute — a number can drive a metronome and
a starting-chord playback where *Andante* cannot, and two people will not agree
what *Andante* means. noteman's column is currently free-form text and needs
changing; see [`bundle-format.md`](bundle-format.md).
Rehearsal MIDI and MP3s are deliberately out of the first bundle.
### One rule for the import side
**Import creates a new song only; never re-import onto an existing one.** Jump
destinations reference slices by ID, so replacing a song's slices silently
orphans every marker on it. Re-cutting happens *before* marker authoring in
practice, so forbidding it costs nothing and prevents a genuinely nasty data-loss
mode. Re-export from the project file is the supported path.
## Implementation
**Python**, chosen for OpenCV access and iteration speed. Installed as a package
via `uv tool install --editable .`, which puts a `noteman-slicer` command on PATH
that runs from any directory with no venv to activate. The one cwd trap: load
bundled data via `Path(__file__).parent` or `importlib.resources`, never a
relative path.
Dependencies: **PyMuPDF**, **PySide6**, **opencv-python-headless**, **numpy** —
all wheels, no system packages. PyMuPDF covers every PDF need; see
[ADR 0005](adr/0005-pymupdf-for-all-pdf-access.md).
Verified: `cv2` 5.0.0 writes 4-channel lossless WebP with alpha preserved
byte-exact (`IMWRITE_WEBP_QUALITY, 101`).
Module boundaries: `pdf.py` (load, source-type detect, rasterize), `detect.py`
(deskew, row-darkness profile, system runs, staff height), `bundle.py`,
`editor.py`.
## Changes required in noteman
On noteman's timeline, not the slicer's — but release 1 produces artifacts
nothing consumes until this lands.
1. **Delete the sharp normalisation pipeline.** The slicer's output is final.
2. **Bundle import** — unzip → read `song.json` → create song → insert slices in
array order → insert markers, mapping index → new slice UUID → store the PDF.
3. **Jump sources carry explicit destinations** — `destinationSliceId` is already
nullable on every marker type, so this is viewer logic, not schema.
SVG support on the noteman side (`image/svg+xml` in the upload path, `.svg` in
`CONTENT_TYPES`, and a CSP header on SVG responses) is not needed until the SVG
renderer ships.
## Phasing
**Release 1 — editor + detection + bundle export, raster only.** Vector PDFs are
rasterized like everything else; they're the clean case, where deskew is a no-op
and detection works best. Levels, content rectangle, discard, markers, project
file.
Everything else is deferred and tracked as issues on the Gitea repo.
## Reference values
- Final slice width cap: **1920px**, matching the viewer sheet's max-width. A
ceiling, not a target.
- Output format: **lossless WebP**.
- Working resolution:
- **Scanned sources — the embedded image's native resolution.** Never
re-render. Real scans in this corpus run ~200 DPI (1653×2332 for A4), which
is *below* the 1920 cap, so those songs ship narrower than 1920 and are never
upscaled.
- **Vector sources — 600 DPI**, configurable. A4 @ 600 DPI is ~4960×7016 px;
the ~2.6× downsample to 1920 is itself a quality win via antialiasing. 300
DPI would suffice for the target, but 600 buys headroom for deskew
resampling.
- A slice = **one system** = one full line of music across all voices, typically
4–12 bars, lyrics intact.
- Upload/bundle sizes are not constrained by noteman's old 25 MB/file limits —
the bundle bypasses that path entirely.
noteman_slicer/__init__.py
+1
View File
@@ -0,0 +1 @@
__version__ = "0.1.0"
noteman_slicer/bundle.py
+387
View File
@@ -0,0 +1,387 @@
"""Bundle export — the only channel to noteman (ADR 0001).
song.zip
song.json
original.pdf
001.webp 002.webp …
Array order in `song.json` *is* slice order: one ordering, not two. Markers
nest inside the slice they sit on, so an index appears in exactly one place —
a jump source's `destination`.
"""
from __future__ import annotations
import json
import re
import zipfile
from pathlib import Path
from .pdf import Source
from .project import Project
from .render import render_song
FORMAT_VERSION = 1
METADATA_FIELDS = (
"title",
"subtitle",
"composer",
"original_artist",
"arranger",
"lyricist",
"translator",
"tempo",
"voices",
)
# Beats per minute, exported as a JSON number. A figure is worth more than a
# word here: "Andante" cannot drive a metronome and two people will not agree
# what it means.
NUMERIC_FIELDS = frozenset({"tempo"})
def filename(project: Project) -> str:
"""The bundle's name, from the song's title.
Spaces become dashes and anything that is not a letter, digit, dash, dot or
underscore goes. Letters keep their accents — ä and ö are not a filesystem's
problem — but a leading dot would make the bundle invisible.
"""
# Drop the unsafe characters before collapsing whitespace, not after, or
# "Sävel & Ääni" keeps the dash the ampersand left behind.
title = re.sub(r"[^\w\s.-]", "", (project.metadata.get("title") or ""))
return f"{re.sub(r'\s+', '-', title.strip()).lstrip('.-') or 'song'}.zip"
def _engraving(project: Project, page: int, slot: int) -> dict | None:
"""The notation behind a re-engraved slice, or None for a scanned one.
The slice image stays the presentation; this is the notation it was made
from, carried so the music can be edited again or turned into sound. Key
and time are resolved against the song defaults here — a consumer reading
one slice should not have to know what the rest of the song inherited.
"""
replacement = project.pages[page].replacements[slot]
if not replacement or not replacement.voices:
return None
return {
"lang": "lilypond",
"key": replacement.key or project.key,
"time": replacement.time or project.time,
"print_time": replacement.print_time,
"voices": [
{"clef": v.clef, "notes": v.notes.strip()}
| ({"lyrics": v.lyrics.strip()} if v.lyrics.strip() else {})
for v in replacement.voices
],
}
def _source(project: Project) -> dict:
"""How the slices were cut from the archived PDF.
Without this a bundle is a one-way trip: the images are output and the cuts
that made them live only in the producer's own project file, so reopening
someone else's bundle would mean cutting the score again from scratch. It
is geometry in normalised page coordinates, so it survives the PDF being
rendered at any resolution.
Only the pages are here. Which slot on which page a slice came from is on
the slice itself, so that one ordering — the slices array — stays the only
one, and a slot no slice claims is a slot that was discarded.
"""
return {
"file": "original.pdf",
"pages": [
{
"skew": round(page.skew, 2),
"content": [round(v, 5) for v in project.page_content_rect(i)],
"levels": list(project.page_levels(i)),
"cuts": [[[round(x, 5), round(y, 5)] for x, y in cut.points] for cut in page.cuts],
}
for i, page in enumerate(project.pages)
],
}
def song_json(project: Project, files: list[str]) -> dict:
payload: dict = {"v": FORMAT_VERSION}
for field in METADATA_FIELDS:
value = (project.metadata.get(field) or "").strip()
if not value:
continue
if field in NUMERIC_FIELDS:
try:
payload[field] = int(value)
except ValueError:
continue # not a number, so not worth exporting as one
else:
payload[field] = value
kept = project.kept_slices()
# Markers reference slices by (page, slot) while editing, because that is
# what survives adding and removing cuts. In the bundle they become the
# array index, which is the only cross-reference the format has.
index_of = {position: i for i, position in enumerate(kept)}
slices: list[dict] = []
for name, (page, slot) in zip(files, kept):
entry: dict = {"file": name, "page": page, "slot": slot}
bar = project.pages[page].bars[slot]
if bar:
entry["bar"] = bar
engraving = _engraving(project, page, slot)
if engraving:
entry["engraving"] = engraving
markers = []
for marker in project.pages[page].markers[slot]:
item: dict = {"type": marker.type}
if marker.label:
item["label"] = marker.label
if marker.destination is not None:
target = index_of.get(tuple(marker.destination))
# A jump whose target was discarded or re-cut away is dropped
# rather than exported dangling: noteman would have nothing to
# resolve it to.
if target is None:
continue
item["destination"] = target
markers.append(item)
if markers:
entry["markers"] = markers
slices.append(entry)
payload["slices"] = slices
if project.source.exists():
payload["source"] = _source(project)
return payload
def write(project: Project, source: Source, path: Path) -> Path:
"""Render the song and write the bundle. Returns the zip path.
A title is required; every other metadata field is optional. noteman's own
rule is that a song needs a title and at least one slice, and a bundle that
cannot become a song is not worth writing.
"""
if not project.metadata.get("title", "").strip():
raise ValueError("a title is required before a song can be exported")
images = render_song(project, source)
if not images:
raise ValueError("no slices to export — every slice is discarded")
names = [f"{i + 1:03}.webp" for i in range(len(images))]
path = Path(path)
path.parent.mkdir(parents=True, exist_ok=True)
# ZIP_STORED for the images: WebP is already compressed, so deflating it
# only costs time. The JSON is small enough not to care.
with zipfile.ZipFile(path, "w") as zf:
zf.writestr(
"song.json",
json.dumps(song_json(project, names), indent=2, ensure_ascii=False),
zipfile.ZIP_DEFLATED,
)
if project.source.exists():
pdf = project.source.read_bytes()
if project.optimise_pdf:
import pymupdf
from .pdfopt import optimise
shrunk, _ = optimise(pymupdf.open(project.source), len(pdf))
pdf = shrunk or pdf # empty means it found no saving
zf.writestr("original.pdf", pdf, zipfile.ZIP_STORED)
for name, data in zip(names, images):
zf.writestr(name, data, zipfile.ZIP_STORED)
# The project is spent once its song has been exported: the next edit
# session starts fresh from detection rather than resuming these decisions.
# Recorded here so no caller can forget it.
project.exported = True
project.save()
return path
class NoCuts(ValueError):
"""The bundle carries no `source` block, so its cuts cannot be restored."""
def _pages_from(geometry: dict, slices: list[dict]):
"""Rebuild the pages from a manifest's source geometry."""
from .project import Cut, Page
# Every slot on a page exists; the ones no slice claims were discarded.
# That is the one thing the bundle states by omission rather than directly,
# since shipping a discarded slice's image would defeat discarding it.
claimed = {(s["page"], s["slot"]) for s in slices}
pages = []
for i, page in enumerate(geometry["pages"]):
cuts = [Cut([tuple(p) for p in cut]) for cut in page["cuts"]]
count = len(cuts) + 1
pages.append(
Page(
skew=page.get("skew", 0.0),
cuts=cuts,
discards=[(i, slot) not in claimed for slot in range(count)],
markers=[[] for _ in range(count)],
replacements=[None] * count,
bars=[None] * count,
content_rect=tuple(page["content"]) if page.get("content") else None,
levels=tuple(page["levels"]) if page.get("levels") else None,
)
)
return pages
def _pages_from_detection(pdf: Path):
"""Cut the PDF again from scratch, for a bundle that recorded no geometry."""
from .detect import detect_page
from .pdf import open_source, page_raster
from .project import Project
source = open_source(pdf)
detections, heights = [], []
try:
for i in range(len(source)):
gray = page_raster(source, i)
detections.append(detect_page(gray))
heights.append(gray.shape[0])
finally:
source.close()
return Project.from_detection(pdf, detections, heights)
def _restore(project, slices: list[dict], positions: list[tuple[int, int]]) -> None:
"""Put each slice's bar number, markers and engraving back on its slot."""
from .project import Marker, Replacement, Voice
for entry, (page, slot) in zip(slices, positions):
project.pages[page].bars[slot] = entry.get("bar")
project.pages[page].markers[slot] = [
Marker(
type=marker["type"],
label=marker.get("label"),
# Back from an array index to the (page, slot) the editor works
# in — the inverse of what export does.
destination=(
positions[marker["destination"]]
if marker.get("destination") is not None
and marker["destination"] < len(positions)
else None
),
)
for marker in entry.get("markers", [])
]
engraving = entry.get("engraving")
if engraving and engraving.get("lang") == "lilypond":
project.pages[page].replacements[slot] = Replacement(
voices=[
Voice(
clef=v.get("clef", "treble"),
notes=v.get("notes", ""),
lyrics=v.get("lyrics", ""),
)
for v in engraving.get("voices", [])
],
print_time=engraving.get("print_time", False),
)
for entry in slices:
# Key and time are per slice in the bundle and per song here; the first
# engraving that states them is as good a song default as exists.
engraving = entry.get("engraving") or {}
if engraving.get("key"):
project.key = engraving["key"]
project.time = engraving.get("time", project.time)
break
def has_cuts(path: Path) -> bool:
"""Whether this bundle records the geometry its slices were cut with.
Worth asking before unpacking, since the answer decides whether reopening
is a round trip or a fresh session with the same PDF.
"""
with zipfile.ZipFile(Path(path)) as zf:
if "song.json" not in zf.namelist():
return False
return bool(json.loads(zf.read("song.json")).get("source"))
def read(
path: Path, into: Path | None = None, *, force: bool = False, detect: bool = False
) -> tuple[Project, Path]:
"""Unpack a bundle back into an editable project. Returns it and its PDF.
The archived PDF is written out beside the bundle and becomes the project's
source again, because the PDF is what the pipeline renders from — the slice
images in the zip are output, and are discarded rather than re-imported.
The cuts, skew, levels and content rectangles come from the manifest's
`source` block, so this is a real round trip rather than a re-detection
that happens to land nearby. A bundle written without one raises `NoCuts`;
`detect` says to cut the PDF from scratch instead, which is a different
thing and worth a caller asking about first.
"""
from .project import Project, default_path, hash_file
path = Path(path)
with zipfile.ZipFile(path) as zf:
names = set(zf.namelist())
if "song.json" not in names:
raise ValueError(f"{path.name} is not a bundle: no song.json")
manifest = json.loads(zf.read("song.json"))
if manifest.get("v") != FORMAT_VERSION:
raise ValueError(f"unsupported bundle version {manifest.get('v')!r}")
geometry = manifest.get("source")
if not geometry and not detect:
raise NoCuts(
f"{path.name} carries no cuts — it was written by a producer that "
"does not record them"
)
pdf_name = (geometry or {}).get("file", "original.pdf")
if pdf_name not in names:
raise ValueError(f"{path.name} names {pdf_name} but does not contain it")
pdf_bytes = zf.read(pdf_name)
# Unpacking writes two files. Refuse to land on either if it is already
# there: the obvious place to open a bundle is next to the score it came
# from, and that is exactly where someone's unfinished cuts live.
target = Path(into) if into else path.with_suffix(".pdf")
existing = [f for f in (target, default_path(target)) if f.exists()]
if existing and not force:
raise ValueError(
f"{', '.join(f.name for f in existing)} already exists — "
"open it with --pdf elsewhere, or --force to overwrite"
)
target.write_bytes(pdf_bytes)
slices = manifest["slices"]
if geometry:
pages_json = geometry["pages"]
first = pages_json[0] if pages_json else {}
project = Project(
source=target,
source_hash=hash_file(target),
pages=_pages_from(geometry, slices),
content_rect=tuple(first.get("content", (0.0, 0.0, 1.0, 1.0))),
levels=tuple(first.get("levels", (0, 255))),
path=default_path(target),
)
positions = [(s["page"], s["slot"]) for s in slices]
else:
project = _pages_from_detection(target)
project.path = default_path(target)
# Detection's slices are in reading order and so are the bundle's, so
# they can be lined up — but only if there are exactly as many. One
# system found or missed shifts every marker onto the wrong slice,
# which is worse than not placing them at all.
positions = project.kept_slices()
if len(positions) != len(slices):
positions = []
project.metadata = {
field: str(manifest[field]) for field in METADATA_FIELDS if manifest.get(field) is not None
}
_restore(project, slices[: len(positions)], positions)
return project, target
noteman_slicer/cli.py
+237
View File
@@ -0,0 +1,237 @@
"""Command line entry point."""
from __future__ import annotations
import argparse
import sys
import numpy as np
from pathlib import Path
from . import __version__, overlay
from .detect import detect_page
from .pdf import SourceType, open_source, page_raster
def _info(args: argparse.Namespace) -> int:
source = open_source(args.pdf, SourceType(args.type) if args.type else None)
note = f" (detected {source.detected.value}, overridden)" if source.overridden else ""
print(f"{source.path.name}: {source.type.value}{note}, {len(source)} pages")
for i in range(len(source)):
h, w = page_raster(source, i).shape
print(f" p{i + 1:<3} {w}x{h}")
source.close()
return 0
def _detect(args: argparse.Namespace) -> int:
source = open_source(args.pdf, SourceType(args.type) if args.type else None)
out = Path(args.out)
out.mkdir(parents=True, exist_ok=True)
pages = range(len(source)) if args.page is None else [args.page - 1]
for i in pages:
gray = page_raster(source, i)
detection = detect_page(gray)
staves = [s.staff_height for s in detection.systems if s.staff_height]
note = f", staff {np.median(staves):.0f}px" if staves else ""
print(
f"p{i + 1:<3} skew {detection.skew:+.2f}° "
f"{len(detection.systems)} systems{note}"
f"{' (no bracket)' if detection.bracketless else ''}"
)
for n, system in enumerate(detection.systems, 1):
print(f" sys{n}: {system.top}–{system.bottom} h={system.height}")
overlay.write(gray, detection, out / f"{source.path.stem}-p{i + 1:02}.png")
print(f"overlays written to {out}/")
source.close()
return 0
def _project(args: argparse.Namespace) -> int:
from .project import default_path, open_project
source = open_source(args.pdf, SourceType(args.type) if args.type else None)
path = default_path(source.path)
project = open_project(source, resume=args.resume and not args.force)
if project.path is None:
print(f"{path.name}: fresh session from detection")
else:
print(f"{path.name}: resumed")
if project.source_changed():
print(" WARNING: the PDF has changed since these cuts were made")
kept = project.kept_slices()
for i, page in enumerate(project.pages):
flags = "".join("." if d else "#" for d in page.discards)
print(f" p{i + 1:<3} skew {page.skew:+.2f}° {page.slice_count} slices [{flags}]")
print(f" {len(kept)} slices kept, {sum(p.slice_count for p in project.pages) - len(kept)} discarded")
if args.save:
print(f" saved to {project.save(path)}")
source.close()
return 0
def _export(args: argparse.Namespace) -> int:
from . import bundle
from .project import open_project
source = open_source(args.pdf, SourceType(args.type) if args.type else None)
project = open_project(source, resume=args.resume)
if project.path is None:
print("no unspent project state; exporting straight from detection")
elif project.source_changed():
print("WARNING: the PDF has changed since these cuts were made")
out = Path(args.out) if args.out else source.path.with_name(bundle.filename(project))
try:
bundle.write(project, source, out)
except ValueError as error:
print(f"cannot export: {error}")
print(" set one with: noteman-slicer edit … (Song → Title)")
source.close()
return 1
size = out.stat().st_size
slices = len(project.kept_slices())
print(f"{out} {slices} slices, {size / 1024:.0f} KB ({size / max(slices, 1) / 1024:.1f} KB/slice)")
source.close()
return 0
def _confirm(question: str) -> bool:
"""Ask before doing something the caller did not ask for. No tty, no."""
if not sys.stdin.isatty():
print(f"{question} (not a terminal — pass --detect to say yes)")
return False
return input(f"{question} [y/N] ").strip().lower() in ("y", "yes")
def _open(args: argparse.Namespace) -> int:
from . import bundle
from .editor import launch
zip_path, where = Path(args.zip), Path(args.pdf) if args.pdf else None
try:
cuts = bundle.has_cuts(zip_path)
except (OSError, ValueError) as error:
print(f"cannot open: {error}")
return 1
if not cuts and not args.detect:
print(f"{zip_path.name} carries no cuts — it was written by a producer that")
print("does not record them. Its PDF can be cut again from scratch, but that")
print("is a fresh session: the cuts will be detection's, and the markers land")
print("only if detection happens to find the same number of slices.")
if not _confirm("Open it that way?"):
return 1
try:
project, pdf = bundle.read(zip_path, where, force=args.force, detect=not cuts)
except (ValueError, KeyError) as error:
print(f"cannot open: {error}")
return 1
saved = project.save()
kept = project.kept_slices()
print(f"{pdf.name}: {len(project.pages)} pages, {len(kept)} slices")
if not cuts:
marked = sum(len(m) for page in project.pages for m in page.markers)
print(" cut from scratch by detection — check every cut before exporting")
print(
f" {marked} markers placed by position"
if marked
else " markers not placed: detection found a different number of slices"
)
print(f" project written to {saved.name}")
if args.no_edit:
return 0
return launch(pdf, resume=True)
def _edit(args: argparse.Namespace) -> int:
from .editor import launch
return launch(
Path(args.pdf), SourceType(args.type) if args.type else None, resume=args.resume
)
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(
prog="noteman-slicer",
description="Cut score PDFs into noteman's slice images and markers.",
)
parser.add_argument("--version", action="version", version=__version__)
sub = parser.add_subparsers(dest="command", required=True)
info = sub.add_parser("info", help="classify a PDF and report its page rasters")
info.add_argument("pdf")
info.add_argument(
"--type",
choices=[t.value for t in SourceType],
help="override source-type detection",
)
info.set_defaults(func=_info)
det = sub.add_parser("detect", help="run detection and write debug overlays")
det.add_argument("pdf")
det.add_argument("--out", default="overlays", help="output directory")
det.add_argument("--page", type=int, help="single 1-based page instead of all")
det.add_argument("--type", choices=[t.value for t in SourceType])
det.set_defaults(func=_detect)
proj = sub.add_parser("project", help="create or inspect the project file for a PDF")
proj.add_argument("pdf")
proj.add_argument("--save", action="store_true", help="write the project file")
proj.add_argument("--force", action="store_true", help="re-detect, discarding existing state")
proj.add_argument(
"--resume",
action="store_true",
help="reopen an already-exported project instead of starting fresh",
)
proj.add_argument("--type", choices=[t.value for t in SourceType])
proj.set_defaults(func=_project)
exp = sub.add_parser("export", help="render the song and write a bundle")
exp.add_argument("pdf")
exp.add_argument("--out", help="output zip (default: alongside the PDF)")
exp.add_argument("--resume", action="store_true", help="use already-exported project state")
exp.add_argument("--type", choices=[t.value for t in SourceType])
exp.set_defaults(func=_export)
opn = sub.add_parser("open", help="unpack a bundle back into an editable project")
opn.add_argument("zip")
opn.add_argument("--pdf", help="where to write the archived PDF (default: beside the bundle)")
opn.add_argument(
"--no-edit", action="store_true", help="write the project and stop, without the editor"
)
opn.add_argument(
"--force", action="store_true", help="overwrite an existing PDF or project file"
)
opn.add_argument(
"--detect",
action="store_true",
help="for a bundle with no cuts: cut its PDF from scratch, without asking",
)
opn.set_defaults(func=_open)
ed = sub.add_parser("edit", help="open the editor")
ed.add_argument("pdf")
ed.add_argument(
"--resume",
action="store_true",
help="reopen an already-exported project instead of starting fresh",
)
ed.add_argument("--type", choices=[t.value for t in SourceType])
ed.set_defaults(func=_edit)
args = parser.parse_args(argv)
return args.func(args)
if __name__ == "__main__":
sys.exit(main())
noteman_slicer/detect.py
+416
View File
@@ -0,0 +1,416 @@
"""Detection: skew, systems, cuts, staff height.
Everything here is a *suggestion* the user confirms or edits (ADR 0004).
Nothing downstream may assume a result is right.
Systems are anchored on the vertical bracket that spans their staves, not on
gaps in the row-darkness profile: a row profile cannot tell an inter-staff gap
from an inter-system gap, and gets the count wrong on every page of a
multi-voice choral score (ADR 0006). The row profile is still needed, to expand
each anchor to its true ink extent — a bracket stops at the last staff line,
but the slice must include the lyrics printed below it.
"""
from __future__ import annotations
from dataclasses import dataclass, field
import cv2
import numpy as np
SKEW_LIMIT_DEG = 5.0
SKEW_COARSE_STEP = 1.0
SKEW_FINE_STEP = 0.1
_SKEW_WORK_SCALE = 0.25
_INK = 128 # below this is ink, above is paper
_ANCHOR_KERNEL = 0.03 # vertical open kernel, as a fraction of page height
_ANCHOR_MIN = 0.04 # a bracket is at least this tall, as a fraction of page
_ANCHOR_MAX_RATIO = 2.0 # a stroke this much taller than the typical one is an artefact
_PROFILE_FLOOR = 0.02 # ink-run threshold, as a fraction of the profile peak
_EXPAND_REACH = 1.5 # how far past the bracket a system's ink reaches, in staff heights
_STAFF_KERNEL = 0.05 # horizontal open kernel, as a fraction of page width
_STAFF_MIN_WIDTH = 0.2 # a staff line spans at least this share of the page
_CONTENT_MARGIN = 0.01 # slack past the staff ends, for ledger lines and lyrics
_EDGE_PERCENTILE = 15 # tolerate this share of staff lines merged into scan artefacts
_STAFF_BREAK = 2.5 # a gap this many line-spacings wide separates two staves
_STAFF_LINES = 4 # lines a group needs to be a staff rather than an extender (5, minus one for a broken line)
@dataclass
class Anchor:
"""A system's vertical bracket: where it is, and how far left it reaches."""
top: int
bottom: int
left: int
@dataclass
class System:
"""One line of music: the ink extent that becomes a slice."""
top: int
bottom: int
staff_height: float | None = None
@property
def height(self) -> int:
return self.bottom - self.top
@dataclass
class PageDetection:
skew: float
systems: list[System] = field(default_factory=list)
cuts: list[int] = field(default_factory=list)
content: tuple[float, float, float, float] = (0.0, 0.0, 1.0, 1.0)
levels: tuple[int, int] = (0, 255)
@property
def bracketless(self) -> bool:
"""True when no bracket was found and the row profile was used alone."""
return not self.systems or all(s.staff_height is None for s in self.systems)
def row_darkness(gray: np.ndarray) -> np.ndarray:
return (255 - gray.astype(np.float32)).sum(axis=1)
def deskew_angle(gray: np.ndarray) -> float:
"""Angle maximising row-darkness variance — staff lines are the signal.
Coarse then fine, on a downscaled copy: 31 warps instead of 101.
"""
work = cv2.resize(gray, None, fx=_SKEW_WORK_SCALE, fy=_SKEW_WORK_SCALE,
interpolation=cv2.INTER_AREA)
def score(angle: float) -> float:
return float(row_darkness(_rotate(work, angle, cv2.INTER_LINEAR)).var())
coarse = np.arange(-SKEW_LIMIT_DEG, SKEW_LIMIT_DEG + 1e-9, SKEW_COARSE_STEP)
best = max(coarse, key=score)
fine = np.arange(best - SKEW_COARSE_STEP, best + SKEW_COARSE_STEP + 1e-9, SKEW_FINE_STEP)
fine = fine[np.abs(fine) <= SKEW_LIMIT_DEG]
return round(float(max(fine, key=score)), 2)
def _rotate(gray: np.ndarray, angle: float, flags: int = cv2.INTER_CUBIC) -> np.ndarray:
if angle == 0.0:
return gray
h, w = gray.shape
m = cv2.getRotationMatrix2D((w / 2, h / 2), angle, 1.0)
return cv2.warpAffine(gray, m, (w, h), flags=flags, borderValue=255)
def deskew(gray: np.ndarray, angle: float) -> np.ndarray:
return _rotate(gray, angle)
def system_anchors(gray: np.ndarray) -> list[Anchor]:
"""The vertical brackets, one per system."""
h = gray.shape[0]
binary = (gray < _INK).astype(np.uint8)
kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (1, max(3, int(h * _ANCHOR_KERNEL))))
strokes = cv2.morphologyEx(binary, cv2.MORPH_OPEN, kernel)
count, _, stats, _ = cv2.connectedComponentsWithStats(strokes, 8)
tall = [
Anchor(
int(stats[i, cv2.CC_STAT_TOP]),
int(stats[i, cv2.CC_STAT_TOP] + stats[i, cv2.CC_STAT_HEIGHT]),
int(stats[i, cv2.CC_STAT_LEFT]),
)
for i in range(1, count)
if stats[i, cv2.CC_STAT_HEIGHT] > h * _ANCHOR_MIN
]
# A scanner leaves a dark line down the sheet edge — the binder shadow, the
# glass, the page next to it — and it runs the whole height of the scan.
# Being the tallest stroke on the page it wins every overlap below and
# swallows every system into one. A page's brackets and barlines are all
# about one system tall, so anything wildly taller than the typical stroke
# is not notation. Relative, not an absolute fraction of the page: a page
# holding one big system is legitimate and must survive.
if len(tall) > 1:
limit = float(np.median([a.bottom - a.top for a in tall])) * _ANCHOR_MAX_RATIO
tall = [a for a in tall if a.bottom - a.top <= limit] or tall
# Tallest first, keeping only strokes that don't overlap one already kept:
# a system's barlines all overlap its bracket, so each system yields one.
# The kept stroke is the tallest, which is the bracket rather than a barline.
anchors: list[Anchor] = []
for candidate in sorted(tall, key=lambda a: a.bottom - a.top, reverse=True):
if any(not (candidate.bottom < a.top or candidate.top > a.bottom) for a in anchors):
continue
anchors.append(candidate)
return sorted(anchors, key=lambda a: a.top)
def content_columns(
gray: np.ndarray, anchors: list[Anchor] | None = None
) -> tuple[float, float]:
"""Where the music is horizontally, as normalised x bounds.
Staff lines are long *horizontal* runs; a scan-edge shadow, a spine
darkening and the vertical line a dirty scanner glass leaves are all
*vertical*. Opening with a wide flat kernel keeps the first and erases the
others, so the staff lines' own bounding box is the music area.
`anchors` does two jobs. It restricts the search to rows known to hold
systems — without that, a horizontal scan artefact above or below the music
is itself a long horizontal run reaching the paper edge, which is exactly
the measurement being avoided. And its brackets give the true left bound:
a bracket sits *left of every staff line*, so a bound taken from staff
lines alone crops it off, and a bracket is notation, not artefact.
This matters more than it looks: trim is tight and per slice, so one dark
band down the margin sets that slice's width, which sets the song's widest
slice, which scales the whole song down.
"""
height, width = gray.shape
binary = (gray < _INK).astype(np.uint8)
if anchors:
keep = np.zeros(height, bool)
for anchor in anchors:
keep[max(0, anchor.top) : min(height, anchor.bottom)] = True
binary[~keep] = 0
kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (max(3, int(width * _STAFF_KERNEL)), 1))
lines = cv2.morphologyEx(binary, cv2.MORPH_OPEN, kernel)
count, _, stats, _ = cv2.connectedComponentsWithStats(lines, 8)
runs = [
(stats[i, cv2.CC_STAT_LEFT], stats[i, cv2.CC_STAT_LEFT] + stats[i, cv2.CC_STAT_WIDTH])
for i in range(1, count)
if stats[i, cv2.CC_STAT_WIDTH] > width * _STAFF_MIN_WIDTH
]
if not runs:
return 0.0, 1.0
# Percentiles, not the extremes. Where a scan-edge band happens to touch
# the end of a staff line the two merge into one component, and that
# component then reaches into the artefact — on Ketun joululaulu p2 the
# merged line ends at 1575px against 1544px on the clean page. A page has
# dozens of staff lines and only a few are contaminated, so a percentile
# lands on the true edge while the extreme lands on the worst artefact.
lefts = np.array([r[0] for r in runs], float)
rights = np.array([r[1] for r in runs], float)
margin = width * _CONTENT_MARGIN
left = float(np.percentile(lefts, _EDGE_PERCENTILE))
if anchors:
left = min(left, min(a.left for a in anchors))
right = float(np.percentile(rights, 100 - _EDGE_PERCENTILE))
return max(0.0, left - margin) / width, min(float(width), right + margin) / width
def staff_count(gray: np.ndarray) -> int:
"""How many staves are in this slice — i.e. how many voices it holds.
Kaipaava's first four systems have two staves and its fifth has five, so
this cannot be a song-level constant. Counts long horizontal runs and
divides by the five lines a staff has; the same signal that finds the music
area, so it degrades the same way and no worse.
"""
height, width = gray.shape
binary = (gray < _INK).astype(np.uint8)
kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (max(3, int(width * _STAFF_KERNEL)), 1))
lines = cv2.morphologyEx(binary, cv2.MORPH_OPEN, kernel)
count, _, stats, _ = cv2.connectedComponentsWithStats(lines, 8)
rows = sorted(
stats[i, cv2.CC_STAT_TOP]
for i in range(1, count)
if stats[i, cv2.CC_STAT_WIDTH] > width * _STAFF_MIN_WIDTH
)
if not rows:
return 1
# Compare against the *line* spacing, not the staff height: adjacent staves
# can sit closer together than one staff is tall, so a staff-height
# threshold merges them into one.
line_spacing = (staff_height(gray, 0, height) or height * 0.05) / 4
groups: list[list[int]] = [[rows[0]]]
for row in rows[1:]:
if row - groups[-1][-1] > line_spacing * _STAFF_BREAK:
groups.append([])
groups[-1].append(row)
# A staff is five evenly spaced lines. Lone long runs are lyric extenders —
# Engel's "uh______" — and hairpins, which are just as horizontal as a
# staff line and would otherwise each count as a staff.
staves = sum(1 for group in groups if len(group) >= _STAFF_LINES)
return max(1, staves)
def ink_runs(gray: np.ndarray) -> list[tuple[int, int]]:
"""Rows containing ink, despeckled — specks are the known failure mode."""
profile = row_darkness(cv2.medianBlur(gray, 3))
if profile.max() <= 0:
return []
inked = profile > profile.max() * _PROFILE_FLOOR
runs: list[tuple[int, int]] = []
start: int | None = None
for i, on in enumerate(inked):
if on and start is None:
start = i
elif not on and start is not None:
runs.append((start, i))
start = None
if start is not None:
runs.append((start, len(inked)))
return runs
def staff_height(gray: np.ndarray, top: int, bottom: int) -> float | None:
"""Distance between a staff's outer lines, from staff-line spacing."""
profile = row_darkness(gray[top:bottom])
if profile.size == 0 or profile.max() <= 0:
return None
peaks = np.where(profile > profile.max() * 0.55)[0]
if peaks.size < 2:
return None
centres = []
run = [peaks[0]]
for prev, cur in zip(peaks, peaks[1:]):
if cur - prev > 3:
centres.append(float(np.mean(run)))
run = []
run.append(cur)
centres.append(float(np.mean(run)))
if len(centres) < 2:
return None
gaps = np.diff(centres)
# Keep intra-staff gaps; the big ones are the spaces between staves.
intra = gaps[gaps < np.median(gaps) * 2]
if intra.size == 0:
return None
return float(np.median(intra) * 4) # 5 lines, 4 spaces
def ink_levels(gray: np.ndarray) -> tuple[int, int]:
"""Black and white points that put the ink on black and the paper on white.
Left at 0–255 a slice ships whatever grey the scanner produced, and the
downscale to the song's width then blends every stroke edge further, so a
fine engraving arrives on the tablet as a wash. Notation is two-tone by
nature — ink and paper, nothing in between — so Otsu's split is exactly the
measurement wanted, and the points sit halfway to each end of the range from
it. Halfway rather than at the split itself: the ramp between them is the
antialiasing, and collapsing it would leave the notes jagged.
"""
split = float(cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)[0])
if split < 1:
# A page already scanned bilevel has no interior split to find, and
# Otsu degenerates to 0. There is nothing between ink and paper to
# stretch, so leave the sliders where they are.
return 0, 255
return int(split / 2), int(split + (255 - split) / 2)
def _gap(run: tuple[int, int], anchor: Anchor) -> int:
"""Vertical distance between an ink run and a bracket; 0 if they overlap."""
start, end = run
if end > anchor.top and start < anchor.bottom:
return 0
return anchor.top - end if end <= anchor.top else start - anchor.bottom
def _assign(
runs: list[tuple[int, int]],
anchors: list[Anchor],
reaches: list[float],
) -> list[tuple[int, int]]:
"""Give every ink run to one system, and return each system's extent.
A run between two systems is resolved by **precedence, not proximity**: the
system above wins if the run is within its reach. Text printed under a staff
belongs to that staff, and engravers space lyrics generously — on *Feliz
Navidad* a lyric line sits 43px under its own system's bracket but only 10px
above the next one's, so nearest-bracket gives it to the wrong system.
Distance is measured from the *bracket*, never from a growing extent — a
title block's credit lines are stacked closely enough that a chaining
expansion hops from one to the next and walks the whole way up the page.
One pass over all systems, rather than each bracket expanding on its own, so
that a run has exactly one owner and extents cannot overlap.
Known limit: when a lyric line is printed tight enough under its system that
no blank row separates it from the *next* system's staves, the two fuse into
a single ink run and no row profile can split them — the lyric is then given
to the system below and the cut lands high. Dragging the cut is the fix;
separating them needs a signal this pass doesn't have.
"""
bounds = [[a.top, a.bottom] for a in anchors]
def claim(index: int, run: tuple[int, int]) -> None:
bounds[index][0] = min(bounds[index][0], run[0])
bounds[index][1] = max(bounds[index][1], run[1])
for run in runs:
gaps = [_gap(run, a) for a in anchors]
# Ink overlapping a bracket belongs to it — to the one it overlaps most,
# whatever else is in reach.
inside = [
(min(run[1], anchors[i].bottom) - max(run[0], anchors[i].top), i)
for i, g in enumerate(gaps)
if g == 0
]
if inside:
claim(max(inside)[1], run)
continue
within = [i for i, g in enumerate(gaps) if g <= reaches[i]]
if not within:
continue # a title block or a footer: too far from any system
# Otherwise the system above wins, and only failing that the one below.
above = [i for i in within if anchors[i].bottom <= run[0]]
claim(above[-1] if above else within[0], run)
return [(lo, hi) for lo, hi in bounds]
def detect_page(gray: np.ndarray, skew: float | None = None) -> PageDetection:
"""Full proposal for one page raster. `gray` is the *unrotated* page."""
angle = deskew_angle(gray) if skew is None else skew
straight = deskew(gray, angle)
runs = ink_runs(straight)
anchors = system_anchors(straight)
if anchors:
# Staff height is measured on the bracket span, before expansion, so a
# swallowed title block can't distort it.
heights = [staff_height(straight, a.top, a.bottom) for a in anchors]
reaches = [(h or gray.shape[0] * 0.02) * _EXPAND_REACH for h in heights]
systems = [
System(top=lo, bottom=hi, staff_height=h)
for (lo, hi), h in zip(_assign(runs, anchors, reaches), heights)
]
else:
# No bracket: a single-staff melody or lead sheet, where every ink run
# genuinely is its own system.
systems = [System(top=t, bottom=b) for t, b in runs]
cuts = [
(systems[i].bottom + systems[i + 1].top) // 2 for i in range(len(systems) - 1)
]
# Only the horizontal bounds are proposed. Vertically the cuts and the
# discard flags already isolate the header and footer, and cropping the top
# would risk clipping a tempo mark or a section label above the first staff.
left, right = content_columns(straight, anchors)
return PageDetection(
skew=angle,
systems=systems,
cuts=cuts,
content=(left, 0.0, right, 1.0),
levels=ink_levels(straight),
)
noteman_slicer/editor.py
+937
View File
@@ -0,0 +1,937 @@
"""The editor: the human-in-the-loop half of the tool.
Detection proposes; everything here is how you dispose (ADR 0004). Cuts can be
authored entirely by hand with detection producing nothing.
Geometry is edited in normalised page coordinates, so what the screen shows and
what the renderer uses are the same numbers at a different zoom.
"""
from __future__ import annotations
import sys
from pathlib import Path
import numpy as np
from PySide6.QtCore import QPointF, QRectF, Qt, QTimer, Signal
from PySide6.QtGui import (
QAction,
QBrush,
QColor,
QImage,
QIntValidator,
QKeySequence,
QPainter,
QPen,
QPixmap,
QPolygonF,
)
from PySide6.QtWidgets import (
QApplication,
QDoubleSpinBox,
QFileDialog,
QFormLayout,
QGraphicsScene,
QGraphicsView,
QComboBox,
QDialog,
QHBoxLayout,
QLabel,
QLineEdit,
QListWidget,
QMainWindow,
QMessageBox,
QPushButton,
QScrollArea,
QSizePolicy,
QSplitter,
QToolButton,
QVBoxLayout,
QWidget,
)
from . import bundle, lilypond, panel as ui
from .bundle import METADATA_FIELDS, NUMERIC_FIELDS
from .detect import deskew, detect_page
from .pdf import Source, open_source, page_raster
from .project import (
JUMP_TYPES,
LABELLED_TYPES,
MARKER_TYPES,
Cut,
Marker,
Project,
open_project,
)
from .render import apply_levels
PREVIEW_MAX = 1800 # display resolution; geometry stays normalised
PANEL_WIDTH = 340 # starting width only; the splitter takes over from there
HIT = 6 # grab distance in screen pixels
AUTOSAVE_MS = 800
_CUT = QColor(220, 40, 40)
_CUT_ACTIVE = QColor(255, 120, 0)
_VERTEX = QColor(255, 200, 0)
_DISCARD = QColor(120, 120, 140, 90)
_SELECT = QColor(0, 170, 0)
_SELECT_WASH = QColor(0, 200, 60, 40)
_RECT = QColor(40, 140, 220)
_MARKER = QColor(150, 60, 190)
_ENGRAVED = QColor(200, 120, 0)
_ENGRAVED_WASH = QColor(230, 160, 30, 55)
_BADGE_Z = 10
def section(title: str, box: QVBoxLayout, *, expanded: bool = True) -> QVBoxLayout:
"""A collapsible section. Returns the layout its contents go into.
A disclosure arrow, not a checkable QGroupBox: a checkbox in a group
header reads as "enable this feature" rather than "expand this", and a
column of framed boxes with checkboxes is hard to scan. A hairline above
each one does the separating that the frames used to.
"""
box.addWidget(ui.Rule())
header = QToolButton()
header.setText(title.upper())
header.setCheckable(True)
header.setChecked(expanded)
header.setArrowType(Qt.DownArrow if expanded else Qt.RightArrow)
header.setToolButtonStyle(Qt.ToolButtonTextBesideIcon)
header.setAutoRaise(True)
header.setSizePolicy(QSizePolicy.Expanding, QSizePolicy.Fixed)
header.setStyleSheet(ui.HEADING)
body = QWidget()
layout = QVBoxLayout(body)
layout.setContentsMargins(10, 6, 0, 10)
body.setVisible(expanded)
def toggled(open_: bool) -> None:
body.setVisible(open_)
header.setArrowType(Qt.DownArrow if open_ else Qt.RightArrow)
header.toggled.connect(toggled)
box.addWidget(header)
box.addWidget(body)
return layout
class PageView(QGraphicsView):
"""Pan, zoom, and direct manipulation of cuts and the content rectangle."""
changed = Signal()
selection_changed = Signal()
picked = Signal(int, int) # page, slot — a jump target chosen by clicking
engrave_requested = Signal()
def __init__(self) -> None:
super().__init__()
self.setScene(QGraphicsScene(self))
self.setRenderHint(QPainter.Antialiasing)
self.setDragMode(QGraphicsView.ScrollHandDrag)
self.setTransformationAnchor(QGraphicsView.AnchorUnderMouse)
self.project: Project | None = None
self.page_index = 0
self.pixmap: QPixmap | None = None
self.selected_cut: int | None = None
self.selected_slice = 0
self.picking = False
self._drag: tuple[str, int, int] | None = None
self._fitted = False
# -- state ------------------------------------------------------------
def show_page(self, project: Project, index: int, image: np.ndarray) -> None:
self.project = project
self.page_index = index
h, w = image.shape
qimage = QImage(image.data, w, h, w, QImage.Format_Grayscale8).copy()
self.pixmap = QPixmap.fromImage(qimage)
self.selected_cut = None
self.selected_slice = 0
self.scene().setSceneRect(0, 0, w, h)
self.redraw()
self.fitInView(self.scene().sceneRect(), Qt.KeepAspectRatio)
@property
def page(self):
return self.project.pages[self.page_index]
def redraw(self) -> None:
scene = self.scene()
scene.clear()
if self.pixmap is None:
return
scene.addPixmap(self.pixmap)
w, h = self.pixmap.width(), self.pixmap.height()
for slot in range(self.page.slice_count):
if self.page.discards[slot]:
scene.addPolygon(
self._slice_polygon(slot, w, h), QPen(Qt.NoPen), QBrush(_DISCARD)
)
# The selected slice. The outline alone is nearly invisible: its top and
# bottom edges run under the cut lines drawn over them, leaving two thin
# verticals at the page margins. A wash says which slice is selected at
# a glance; the outline stays, because it is what shows trim anomalies.
selected = self._slice_polygon(self.selected_slice, w, h)
scene.addPolygon(selected, QPen(Qt.NoPen), QBrush(_SELECT_WASH))
pen = QPen(_SELECT, 3)
pen.setCosmetic(True)
scene.addPolygon(selected, pen)
x0, y0, x1, y1 = self.project.page_content_rect(self.page_index)
pen = QPen(_RECT, 2, Qt.DashLine)
pen.setCosmetic(True)
scene.addRect(QRectF(x0 * w, y0 * h, (x1 - x0) * w, (y1 - y0) * h), pen)
for slot in range(self.page.slice_count):
above, _ = self.page.bounds(slot)
top = 0 if above is None else int(above.lowest * h)
x = w * 0.015
if self.page.replacements[slot]:
# A wash over the whole slice, not just a label: this slice
# will not ship the pixels underneath it, which is worth
# noticing without hunting for small text.
scene.addPolygon(
self._slice_polygon(slot, w, h), QPen(Qt.NoPen), QBrush(_ENGRAVED_WASH)
)
x = self._badge(scene, x, top + h * 0.004, "ENGRAVED", _ENGRAVED, w)
markers = self.page.markers[slot]
if markers:
self._badge(
scene, x, top + h * 0.004, " · ".join(m.describe() for m in markers), _MARKER, w
)
for i, cut in enumerate(self.page.cuts):
colour = _CUT_ACTIVE if i == self.selected_cut else _CUT
pen = QPen(colour, 2)
pen.setCosmetic(True)
points = [QPointF(px * w, py * h) for px, py in cut.points]
for a, b in zip(points, points[1:]):
line = scene.addLine(a.x(), a.y(), b.x(), b.y(), pen)
line.setZValue(_BADGE_Z)
if i == self.selected_cut:
r = HIT * 1.5 / max(self.transform().m11(), 1e-6)
for p in points:
handle = scene.addEllipse(
p.x() - r, p.y() - r, r * 2, r * 2, QPen(Qt.NoPen), QBrush(_VERTEX)
)
handle.setZValue(_BADGE_Z)
def _badge(self, scene, x: float, y: float, label: str, colour: QColor, w: int) -> float:
"""A filled chip with light text. Returns the x to place the next one."""
text = scene.addText(label)
text.setDefaultTextColor(QColor(255, 255, 255))
scale = max(1.0, w / 900)
text.setScale(scale)
box = text.boundingRect()
pad = 4 * scale
plate = scene.addRect(
x - pad,
y - pad / 2,
box.width() * scale + pad * 2,
box.height() * scale + pad,
QPen(Qt.NoPen),
QBrush(colour),
)
# Above the page pixmap, which sits at z 0: a negative z would put the
# plate behind the scan and the white text with it.
plate.setZValue(_BADGE_Z - 1)
text.setZValue(_BADGE_Z)
text.setPos(x, y)
return x + box.width() * scale + pad * 3
def _slice_polygon(self, slot: int, w: int, h: int) -> QPolygonF:
above, below = self.page.bounds(slot)
top = [(0.0, 0.0), (1.0, 0.0)] if above is None else above.points
bottom = [(0.0, 1.0), (1.0, 1.0)] if below is None else below.points
pts = [QPointF(x * w, y * h) for x, y in top]
pts += [QPointF(x * w, y * h) for x, y in reversed(bottom)]
return QPolygonF(pts)
# -- hit testing ------------------------------------------------------
def _norm(self, pos) -> tuple[float, float]:
p = self.mapToScene(pos)
return p.x() / self.pixmap.width(), p.y() / self.pixmap.height()
def _tolerance(self) -> tuple[float, float]:
scale = max(self.transform().m11(), 1e-6)
return HIT / scale / self.pixmap.width(), HIT / scale / self.pixmap.height()
def _hit_cut(self, x: float, y: float) -> tuple[int, int | None] | None:
"""(cut index, vertex index or None) under the cursor."""
tx, ty = self._tolerance()
for i, cut in enumerate(self.page.cuts):
for v, (vx, vy) in enumerate(cut.points):
if abs(vx - x) <= tx * 2 and abs(vy - y) <= ty * 2:
return i, v
if abs(cut.y_at(x) - y) <= ty:
return i, None
return None
def _hit_rect_edge(self, x: float, y: float) -> str | None:
x0, y0, x1, y1 = self.project.page_content_rect(self.page_index)
tx, ty = self._tolerance()
if y0 - ty <= y <= y1 + ty:
if abs(x - x0) <= tx:
return "left"
if abs(x - x1) <= tx:
return "right"
if x0 - tx <= x <= x1 + tx:
if abs(y - y0) <= ty:
return "top"
if abs(y - y1) <= ty:
return "bottom"
return None
# -- interaction ------------------------------------------------------
def mousePressEvent(self, event) -> None:
if self.project is None or self.pixmap is None:
return super().mousePressEvent(event)
x, y = self._norm(event.position().toPoint())
if self.picking:
# Choosing a jump's target: click the slice it lands on. Cheaper
# than a thumbnail picker and it reads the score rather than a list.
if event.button() == Qt.LeftButton:
self.picked.emit(self.page_index, self._slice_at(x, y))
self.picking = False
self.setCursor(Qt.ArrowCursor)
return
if event.button() == Qt.RightButton:
hit = self._hit_cut(x, y)
if hit:
index, vertex = hit
if vertex is not None and len(self.page.cuts[index].points) > 2:
self.page.cuts[index].points.pop(vertex)
else:
self.page.remove_cut(index)
self.selected_cut = None
self.redraw()
self.changed.emit()
return
if event.button() == Qt.LeftButton:
edge = self._hit_rect_edge(x, y)
hit = self._hit_cut(x, y)
if hit and event.modifiers() & Qt.ControlModifier and hit[1] is None:
# Ctrl-click on a cut inserts a vertex: this is how a straight
# cut becomes a stepped one.
cut = self.page.cuts[hit[0]]
at = next(i for i, p in enumerate(cut.points) if p[0] > x)
cut.points.insert(at, (x, cut.y_at(x)))
self.selected_cut = hit[0]
self._drag = ("vertex", hit[0], at)
elif hit:
self.selected_cut = hit[0]
self._drag = ("vertex" if hit[1] is not None else "cut", hit[0], hit[1] or 0)
elif edge:
self._drag = ("rect", 0, 0)
self._edge = edge
else:
self.selected_cut = None
self.selected_slice = self._slice_at(x, y)
self.selection_changed.emit()
self.setDragMode(
QGraphicsView.NoDrag if self._drag else QGraphicsView.ScrollHandDrag
)
self.redraw()
super().mousePressEvent(event)
def mouseMoveEvent(self, event) -> None:
if self._drag and self.pixmap is not None:
x, y = self._norm(event.position().toPoint())
kind, index, vertex = self._drag
if kind == "cut":
cut = self.page.cuts[index]
shift = y - cut.y_at(x)
cut.points = [(px, min(1.0, max(0.0, py + shift))) for px, py in cut.points]
elif kind == "vertex":
cut = self.page.cuts[index]
lo = cut.points[vertex - 1][0] if vertex > 0 else 0.0
hi = cut.points[vertex + 1][0] if vertex + 1 < len(cut.points) else 1.0
px = cut.points[vertex][0] if vertex in (0, len(cut.points) - 1) else min(
max(x, lo), hi
)
cut.points[vertex] = (px, min(1.0, max(0.0, y)))
else:
x0, y0, x1, y1 = self.project.page_content_rect(self.page_index)
x, y = min(max(x, 0.0), 1.0), min(max(y, 0.0), 1.0)
box = {
"left": (x, y0, x1, y1),
"right": (x0, y0, x, y1),
"top": (x0, y, x1, y1),
"bottom": (x0, y0, x1, y),
}[self._edge]
self.project.pages[self.page_index].content_rect = box
self.redraw()
return
super().mouseMoveEvent(event)
def mouseReleaseEvent(self, event) -> None:
if self._drag:
self._drag = None
self.setDragMode(QGraphicsView.ScrollHandDrag)
self.page.cuts.sort(key=lambda c: c.points[0][1])
self.changed.emit()
super().mouseReleaseEvent(event)
def mouseDoubleClickEvent(self, event) -> None:
if self.project is None or self.pixmap is None:
return
x, y = self._norm(event.position().toPoint())
if self._hit_cut(x, y) is not None:
return
if event.modifiers() & Qt.ShiftModifier:
# Shift-double-click opens the engrave window on this slice; a
# plain double-click adds a cut, which is by far the commoner one.
self.selected_slice = self._slice_at(x, y)
self.selection_changed.emit()
self.engrave_requested.emit()
return
self.selected_cut = self.page.add_cut(Cut.straight(y))
self.redraw()
self.changed.emit()
def resizeEvent(self, event) -> None:
super().resizeEvent(event)
# The fit in show_page runs before the window has been laid out, when
# the viewport is still its default size, so the first page opens at
# some arbitrary zoom. Redo it once, when the real size arrives.
if not self._fitted and self.pixmap is not None:
self._fitted = True
self.fitInView(self.scene().sceneRect(), Qt.KeepAspectRatio)
def wheelEvent(self, event) -> None:
factor = 1.15 if event.angleDelta().y() > 0 else 1 / 1.15
self.scale(factor, factor)
self.redraw()
def _slice_at(self, x: float, y: float) -> int:
return sum(1 for cut in self.page.cuts if cut.y_at(x) < y)
def toggle_discard(self) -> None:
self.page.discards[self.selected_slice] = not self.page.discards[self.selected_slice]
self.redraw()
self.changed.emit()
class Editor(QMainWindow):
def __init__(self, source: Source, project: Project) -> None:
super().__init__()
self.source = source
self.project = project
self.index = 0
self._raw: dict[int, np.ndarray] = {}
self.setWindowTitle(f"noteman-slicer — {source.path.name}")
self._targeting = 0
self.view = PageView()
self.view.changed.connect(self._touched)
self.view.selection_changed.connect(self._sync)
self.view.picked.connect(self._target_picked)
self.view.engrave_requested.connect(self._open_engrave)
self.autosave = QTimer(self)
self.autosave.setSingleShot(True)
self.autosave.setInterval(AUTOSAVE_MS)
self.autosave.timeout.connect(self._save)
splitter = QSplitter(Qt.Horizontal)
splitter.addWidget(self.view)
splitter.addWidget(self._panel())
splitter.setStretchFactor(0, 1) # the page takes the slack when resized
splitter.setStretchFactor(1, 0)
splitter.setSizes([1100, PANEL_WIDTH])
splitter.setCollapsible(0, False)
self.setCentralWidget(splitter)
self._shortcuts()
self._load_page(0)
# -- ui ---------------------------------------------------------------
def _panel(self) -> QWidget:
inner = QWidget()
box = QVBoxLayout(inner)
box.setContentsMargins(14, 12, 14, 14)
box.setSpacing(0)
scroller = QScrollArea()
scroller.setWidget(inner)
scroller.setWidgetResizable(True)
scroller.setMinimumWidth(280)
self.rail = ui.PageRail()
self.rail.picked.connect(self._load_page)
box.addWidget(self.rail)
page_section = section("Page", box)
form = QFormLayout()
page_section.addLayout(form)
self.skew = QDoubleSpinBox()
self.skew.setRange(-15.0, 15.0)
self.skew.setSingleStep(0.1)
self.skew.setDecimals(2)
self.skew.setSuffix("°")
self.skew.valueChanged.connect(self._skew_changed)
form.addRow("Skew", self.skew)
self.levels = ui.LevelsBar()
self.levels.changed.connect(self._levels_changed)
self.levels.setToolTip(
"Drag the white dot to the foot of the paper hump and the light one "
"to the foot of the ink hump. The strip below is the resulting tone."
)
page_section.addWidget(self.levels)
buttons = QHBoxLayout()
discard = QPushButton("Discard slice")
discard.setToolTip("Or press D. Discarded slices never reach the tablet.")
discard.clicked.connect(self.view.toggle_discard)
reset = QPushButton("Reset crop")
reset.setToolTip("Back to the content rectangle detection proposed for this page")
reset.clicked.connect(self._reset_rect)
buttons.addWidget(discard)
buttons.addWidget(reset)
page_section.addLayout(buttons)
slice_layout = section("This slice", box)
slice_form = QFormLayout()
slice_layout.addLayout(slice_form)
# Every slice can carry one, engraved or scanned: a scanned system has
# a bar number printed on it just the same, and noteman wants to be
# able to say "from bar 33" about either.
self.bar = QLineEdit()
self.bar.setValidator(QIntValidator(1, 9999, self.bar))
self.bar.setProperty("role", "number")
self.bar.setFixedWidth(90)
self.bar.setPlaceholderText("none")
self.bar.setToolTip("The measure this slice starts at, as printed in the score")
self.bar.textChanged.connect(self._bar_changed)
slice_form.addRow("First bar", self.bar)
marker_layout = section("Markers on this slice", box)
self.marker_list = QListWidget()
self.marker_list.setMaximumHeight(110)
marker_layout.addWidget(self.marker_list)
add_row = QHBoxLayout()
self.marker_type = QComboBox()
# Shown as prose, sent as the enum: "D.S. al coda" is what a musician
# reads off the page, `ds_al_coda` is what noteman parses.
for kind in MARKER_TYPES:
self.marker_type.addItem(kind.replace("_", " ").capitalize(), kind)
self.marker_type.currentIndexChanged.connect(
lambda: self._marker_type_changed(self.marker_type.currentData())
)
add_row.addWidget(self.marker_type, 1)
self.marker_label = QLineEdit()
self.marker_label.setPlaceholderText("label")
self.marker_label.setFixedWidth(70)
add_row.addWidget(self.marker_label)
marker_layout.addLayout(add_row)
button_row = QHBoxLayout()
add = QPushButton("Add")
add.clicked.connect(self._add_marker)
remove = QPushButton("Remove")
remove.clicked.connect(self._remove_marker)
self.retarget = QPushButton("Set target…")
self.retarget.clicked.connect(self._pick_target)
for button in (add, remove, self.retarget):
button_row.addWidget(button)
marker_layout.addLayout(button_row)
self._marker_type_changed(self.marker_type.currentData())
# Optional feature: without LilyPond installed the pane never appears,
# and nothing else about the tool changes. Collapsed by default — most
# slices are never re-engraved, and it is the tallest block here.
self.ly_status = None
if lilypond.available():
ly_layout = section("Re-engrave this slice", box, expanded=False)
open_engrave = QPushButton("Open engrave window…")
open_engrave.setToolTip("Or double-click the slice on the page")
open_engrave.clicked.connect(self._open_engrave)
ly_layout.addWidget(open_engrave)
self.ly_status = QLabel()
self.ly_status.setWordWrap(True)
self.ly_status.setProperty("role", "hint")
ly_layout.addWidget(self.ly_status)
meta_layout = section("Song", box)
meta_form = QFormLayout()
meta_layout.addLayout(meta_form)
self.metadata: dict[str, QLineEdit] = {}
for field in METADATA_FIELDS:
edit = QLineEdit(self.project.metadata.get(field, ""))
edit.textChanged.connect(self._metadata_changed)
self.metadata[field] = edit
required = field == "title"
if required:
edit.setPlaceholderText("required")
if field in NUMERIC_FIELDS:
# Beats per minute, and only that: a number can drive a
# metronome where "Andante" cannot.
edit.setValidator(QIntValidator(20, 400, edit))
edit.setPlaceholderText("BPM")
edit.setProperty("role", "number")
edit.setFixedWidth(90)
meta_form.addRow(f"{field.replace('_', ' ').title()}{' *' if required else ''}", edit)
self.optimise = QPushButton("Shrink the original PDF…")
self.optimise.setToolTip("Convert scanned pages to bilevel in the archived PDF")
self.optimise.clicked.connect(self._optimise_pdf)
meta_layout.addWidget(self.optimise)
# Open by default: the first thing a new user needs is to know that a
# double-click adds a cut, and a collapsed section does not tell them.
keys_layout = section("Keys and mouse", box)
keys = QLabel(ui.shortcut_html())
keys.setTextFormat(Qt.RichText)
keys_layout.addWidget(keys)
box.addStretch(1)
# Where you are and the way out, pinned below the scroll. Export is the
# one thing that must never be hidden by however far the panel is
# scrolled, and the count beside it is what says whether it is ready.
footer = QWidget()
column = QVBoxLayout(footer)
column.setContentsMargins(14, 0, 14, 12)
column.addWidget(ui.Rule())
self.summary = QLabel()
self.summary.setWordWrap(True)
self.summary.setProperty("role", "reading")
self.summary.setContentsMargins(0, 10, 0, 6)
column.addWidget(self.summary)
export = QPushButton("Export bundle…")
export.setProperty("role", "primary")
export.clicked.connect(self._export)
column.addWidget(export)
holder = QWidget()
stack = QVBoxLayout(holder)
stack.setContentsMargins(0, 0, 0, 0)
stack.setSpacing(0)
stack.addWidget(scroller, 1)
stack.addWidget(footer)
holder.setMinimumWidth(300)
return holder
def _shortcuts(self) -> None:
for key, slot in (
(QKeySequence("D"), self.view.toggle_discard),
(QKeySequence(Qt.Key_PageDown), lambda: self._load_page(self.index + 1)),
(QKeySequence(Qt.Key_PageUp), lambda: self._load_page(self.index - 1)),
(QKeySequence.Save, self._save),
):
action = QAction(self)
action.setShortcut(key)
action.triggered.connect(slot)
self.addAction(action)
# -- page handling ----------------------------------------------------
def _raster(self, index: int) -> np.ndarray:
"""Page pixels at preview resolution, cached — the PDF is slow to read."""
if index not in self._raw:
import cv2
gray = page_raster(self.source, index)
if gray.shape[1] > PREVIEW_MAX:
k = PREVIEW_MAX / gray.shape[1]
gray = cv2.resize(gray, None, fx=k, fy=k, interpolation=cv2.INTER_AREA)
self._raw[index] = gray
return self._raw[index]
def _preview(self, index: int) -> np.ndarray:
page = self.project.pages[index]
black, white = self.project.page_levels(index)
return np.ascontiguousarray(
apply_levels(deskew(self._raster(index), page.skew), black, white)
)
def _load_page(self, index: int) -> None:
if not 0 <= index < len(self.project.pages):
return
self.index = index
self.view.show_page(self.project, index, self._preview(index))
# The histogram is of the raw scan, not the levelled preview: it has to
# keep showing where the ink is while you drag the points over it.
self.levels.set_page(self._raster(index))
self._sync()
def _sync(self) -> None:
page = self.project.pages[self.index]
self.rail.build([p.slice_count for p in self.project.pages], self.index)
self.skew.blockSignals(True)
self.skew.setValue(page.skew)
self.skew.blockSignals(False)
self.levels.set_levels(*self.project.page_levels(self.index))
bar = page.bars[self.view.selected_slice]
self.bar.blockSignals(True)
self.bar.setText("" if bar is None else str(bar))
self.bar.blockSignals(False)
self._sync_markers()
self._sync_replacement()
kept = len(self.project.kept_slices())
total = sum(p.slice_count for p in self.project.pages)
state = "discarded" if page.discards[self.view.selected_slice] else "kept"
self.summary.setText(
f"page {self.index + 1}/{len(self.project.pages)} · "
f"slice {self.view.selected_slice + 1}/{page.slice_count} is {state}\n"
f"{kept} of {total} slices ship"
)
# -- edits ------------------------------------------------------------
def _touched(self) -> None:
self._sync()
self.autosave.start()
def _bar_changed(self, text: str) -> None:
page = self.project.pages[self.index]
page.bars[self.view.selected_slice] = int(text) if text.strip().isdigit() else None
self.autosave.start()
def _skew_changed(self, value: float) -> None:
self.project.pages[self.index].skew = value
self.view.show_page(self.project, self.index, self._preview(self.index))
self._touched()
def _levels_changed(self, black: int, white: int) -> None:
self.project.pages[self.index].levels = (black, white)
self.view.show_page(self.project, self.index, self._preview(self.index))
self._touched()
# -- markers ----------------------------------------------------------
def _slot_markers(self) -> list[Marker]:
return self.project.pages[self.index].markers[self.view.selected_slice]
def _marker_type_changed(self, kind: str) -> None:
self.marker_label.setEnabled(kind in LABELLED_TYPES)
self.retarget.setEnabled(kind in JUMP_TYPES)
def _add_marker(self) -> None:
kind = self.marker_type.currentData()
label = self.marker_label.text().strip() or None
marker = Marker(type=kind, label=label if kind in LABELLED_TYPES else None)
self._slot_markers().append(marker)
self.marker_label.clear()
self.view.redraw()
self._touched()
if marker.is_jump:
# A jump is useless without a target, so ask for it immediately
# rather than leaving it to be noticed at export.
self._pick_target()
def _remove_marker(self) -> None:
row = self.marker_list.currentRow()
markers = self._slot_markers()
if 0 <= row < len(markers):
markers.pop(row)
self.view.redraw()
self._touched()
def _pick_target(self) -> None:
"""Arm click-to-pick for the selected jump marker."""
markers = self._slot_markers()
row = self.marker_list.currentRow()
candidates = [i for i, m in enumerate(markers) if m.is_jump]
if not candidates:
return
self._targeting = row if row in candidates else candidates[-1]
self.view.picking = True
self.view.setCursor(Qt.CrossCursor)
self.statusBar().showMessage(
"Click the slice this jump goes to — any page, PageUp/PageDown to move"
)
def _target_picked(self, page: int, slot: int) -> None:
markers = self._slot_markers()
if 0 <= self._targeting < len(markers):
markers[self._targeting].destination = (page, slot)
self.view.redraw()
self._touched()
self.statusBar().showMessage(f"target set to p{page + 1} slice {slot + 1}", 2000)
def _sync_markers(self) -> None:
self.marker_list.clear()
for marker in self._slot_markers():
self.marker_list.addItem(marker.describe())
# -- re-engraving -----------------------------------------------------
def _open_engrave(self) -> None:
"""Open the engrave window on the selected slice, showing its pixels."""
from .engrave import EngraveWindow
from .render import cut_slice, slice_mask
slot = self.view.selected_slice
page = self._preview(self.index)
original = cut_slice(page, slice_mask(self.project, self.index, slot, page.shape))
if original is None:
self.statusBar().showMessage("this slice has no ink to replace", 3000)
return
window = EngraveWindow(self.project, self.index, slot, original, self)
window.finished.connect(lambda _: (self.view.redraw(), self._touched()))
window.show()
def _sync_replacement(self) -> None:
if self.ly_status is None:
return
replacement = self.project.pages[self.index].replacements[self.view.selected_slice]
if replacement is None:
self.ly_status.setText("scanned — not re-engraved")
else:
voices = len(replacement.voices)
self.ly_status.setText(f"re-engraved · {voices} voice{'s' if voices != 1 else ''}")
def _metadata_changed(self) -> None:
self.project.metadata = {
field: edit.text().strip() for field, edit in self.metadata.items() if edit.text().strip()
}
self.autosave.start()
def _optimise_pdf(self) -> None:
"""Offer to shrink the archived PDF, showing the result before agreeing.
A before/after crop rather than a checkbox: the failure this can produce
— broken staff lines on a coarse scan — is obvious at a glance and
invisible in a byte count.
"""
import pymupdf
from .pdfopt import Report, optimise, preview
self.statusBar().showMessage("examining the PDF…")
QApplication.processEvents()
source = self.project.source
data, report = optimise(pymupdf.open(source), source.stat().st_size)
self.statusBar().clearMessage()
if not data:
QMessageBox.information(self, "Nothing to shrink", report.summary())
self.project.optimise_pdf = False
return
dialog = QDialog(self)
dialog.setWindowTitle("Shrink the original PDF")
layout = QVBoxLayout(dialog)
text = QLabel(report.summary() + "\n\nThe slices are unaffected — only the archived PDF.")
text.setWordWrap(True)
layout.addWidget(text)
crop = preview(pymupdf.open(source), pymupdf.open(stream=data, filetype="pdf"))
crop = np.ascontiguousarray(crop)
h, w, _ = crop.shape
image = QImage(crop.data, w, h, w * 3, QImage.Format_BGR888).copy()
label = QLabel()
label.setPixmap(QPixmap.fromImage(image))
area = QScrollArea()
area.setWidget(label)
area.setWidgetResizable(True)
area.setMinimumHeight(420)
layout.addWidget(area)
layout.addWidget(QLabel("Original above, shrunk below. Check the staff lines."))
buttons = QHBoxLayout()
use = QPushButton("Use the smaller PDF")
use.clicked.connect(dialog.accept)
keep = QPushButton("Keep the original")
keep.clicked.connect(dialog.reject)
buttons.addWidget(use)
buttons.addWidget(keep)
layout.addLayout(buttons)
dialog.resize(1100, 700)
self.project.optimise_pdf = dialog.exec() == QDialog.Accepted
self._touched()
self.statusBar().showMessage(
"the bundle will carry the shrunk PDF"
if self.project.optimise_pdf
else "the bundle will carry the original PDF",
4000,
)
def _reset_rect(self) -> None:
"""Back to what detection proposed for this page.
Not to the whole page: the proposal is what excludes the scan-edge
junk, so clearing to full width would undo the thing the rectangle
exists for. The preview is already deskewed, so the sweep is skipped.
"""
self.project.pages[self.index].content_rect = detect_page(
self._preview(self.index), skew=0.0
).content
self.view.redraw()
self._touched()
def _save(self) -> None:
path = self.project.save()
self.statusBar().showMessage(f"saved {path.name}", 2000)
def _export(self) -> None:
self._save()
if not self.project.metadata.get("title", "").strip():
QMessageBox.warning(
self, "Title required", "A song needs a title before it can be exported."
)
self.metadata["title"].setFocus()
return
target, _ = QFileDialog.getSaveFileName(
self,
"Export bundle",
str(self.source.path.with_name(bundle.filename(self.project))),
"Bundle (*.zip)",
)
if not target:
return
try:
out = bundle.write(self.project, self.source, Path(target))
except Exception as error: # noqa: BLE001 - surfaced to the user
QMessageBox.critical(self, "Export failed", str(error))
return
size = out.stat().st_size / 1024
QMessageBox.information(
self,
"Exported",
f"{out.name}\n{len(self.project.kept_slices())} slices, {size:.0f} KB\n\n"
"This project is now spent — opening the PDF again starts a fresh "
"session from detection.",
)
def closeEvent(self, event) -> None:
self._save()
super().closeEvent(event)
def launch(pdf: Path, source_type=None, resume: bool = False) -> int:
app = QApplication(sys.argv[:1])
app.setStyleSheet(ui.STYLESHEET)
source = open_source(pdf, source_type)
# An exported project is spent: this opens a fresh session from detection
# rather than resuming decisions that have already been shipped.
project = open_project(source, resume=resume)
if project.path is not None and project.source_changed():
QMessageBox.warning(
None,
"Source changed",
"The PDF has changed since these cuts were made.\n"
"Cuts may no longer line up with the music.",
)
window = Editor(source, project)
window.resize(1500, 950)
window.show()
return app.exec()
noteman_slicer/engrave.py
+322
View File
@@ -0,0 +1,322 @@
"""The engrave window: re-cut a system in LilyPond when the scan is past saving.
Three full-width rows — the scanned original, the render, and the form —
because a system is wide and short, and the job is comparing one against the
other bar by bar.
The form only builds the scaffolding: staff group, clef, key, time. Notes and
lyrics are raw LilyPond, so everything expressive still works, including the
`\\laissezVibrer` / `\\repeatTie` idiom for a tie crossing into the next slice.
"""
from __future__ import annotations
import cv2
import numpy as np
from PySide6.QtCore import Qt
from PySide6.QtGui import QImage, QIntValidator, QKeySequence, QPixmap, QShortcut
from PySide6.QtWidgets import (
QCheckBox,
QComboBox,
QDialog,
QFormLayout,
QHBoxLayout,
QLabel,
QLineEdit,
QPlainTextEdit,
QPushButton,
QScrollArea,
QSplitter,
QVBoxLayout,
QWidget,
)
from . import lilypond, panel as ui
from .detect import staff_height
from .editor import section
from .project import Project, Replacement, Voice
def _pixmap(gray: np.ndarray, width: int = 1200) -> QPixmap:
if gray.shape[1] > width:
k = width / gray.shape[1]
gray = cv2.resize(gray, None, fx=k, fy=k, interpolation=cv2.INTER_AREA)
gray = np.ascontiguousarray(gray)
h, w = gray.shape
return QPixmap.fromImage(QImage(gray.data, w, h, w, QImage.Format_Grayscale8).copy())
class VoiceRow(QWidget):
"""Clef, notes and lyrics for one staff."""
def __init__(self, voice: Voice, index: int, on_change) -> None:
super().__init__()
self.voice = voice
layout = QHBoxLayout(self)
layout.setContentsMargins(0, 2, 0, 2)
self.number = QLabel(f"{index + 1}.")
self.number.setFixedWidth(20)
layout.addWidget(self.number)
self.clef = QComboBox()
for label, value in lilypond.CLEFS:
self.clef.addItem(label, value)
self.clef.setCurrentIndex(max(0, [v for _, v in lilypond.CLEFS].index(voice.clef)))
self.clef.setFixedWidth(130)
self.clef.currentIndexChanged.connect(lambda: (self._pull(), on_change()))
layout.addWidget(self.clef)
self.notes = QLineEdit(voice.notes)
self.notes.setPlaceholderText("notes — c4 d e f | g2 e2")
self.notes.textChanged.connect(lambda: (self._pull(), on_change()))
layout.addWidget(self.notes, 3)
self.lyrics = QLineEdit(voice.lyrics)
self.lyrics.setPlaceholderText("lyrics")
self.lyrics.textChanged.connect(lambda: (self._pull(), on_change()))
layout.addWidget(self.lyrics, 2)
def set_index(self, index: int) -> None:
self.number.setText(f"{index + 1}.")
def _pull(self) -> None:
self.voice.clef = self.clef.currentData()
self.voice.notes = self.notes.text()
self.voice.lyrics = self.lyrics.text()
class EngraveWindow(QDialog):
def __init__(self, project: Project, page: int, slot: int, original: np.ndarray, parent=None):
super().__init__(parent)
self.project = project
self.page_index = page
self.slot = slot
self.original = original
self.setWindowTitle(f"Re-engrave — page {page + 1}, slice {slot + 1}")
self.setModal(False)
self.state = project.pages[page]
self.replacement = self.state.replacements[slot] or self._seed()
self.state.replacements[slot] = self.replacement
rows = QSplitter(Qt.Vertical)
rows.addWidget(self._image_panel("Scanned", _pixmap(original)))
self.render_label = QLabel("not rendered yet")
self.render_label.setAlignment(Qt.AlignCenter)
rows.addWidget(self._image_panel("Engraved", None, self.render_label))
rows.addWidget(self._form())
rows.setSizes([260, 260, 420])
layout = QVBoxLayout(self)
layout.addWidget(rows)
self.resize(1400, 980)
QShortcut(QKeySequence("Ctrl+Return"), self, self.render)
QShortcut(QKeySequence("Ctrl+Enter"), self, self.render)
if any(v.notes.strip() for v in self.replacement.voices):
self.render()
# -- construction -----------------------------------------------------
def _seed(self) -> Replacement:
"""A fresh replacement: voice count from the slice, the rest from the song.
Detecting key or clef on the slice itself would mean reading the very
scan that is too degraded to use, so those are inherited instead — the
song's key does not change, and the clef order repeats system to system.
"""
from .detect import staff_count
count = staff_count(self.original)
clefs = self.project.clefs
return Replacement(
voices=[
Voice(clef=clefs[i] if i < len(clefs) else "treble") for i in range(count)
]
)
def _image_panel(self, title: str, pixmap: QPixmap | None, label: QLabel | None = None):
panel = QWidget()
box = QVBoxLayout(panel)
box.setContentsMargins(0, 0, 0, 0)
heading = QLabel(title)
heading.setStyleSheet(ui.HEADING.replace("QToolButton", "QLabel"))
box.addWidget(heading)
view = label or QLabel()
view.setAlignment(Qt.AlignCenter)
if pixmap is not None:
view.setPixmap(pixmap)
area = QScrollArea()
area.setWidget(view)
area.setWidgetResizable(True)
box.addWidget(area)
return panel
def _form(self) -> QWidget:
panel = QWidget()
box = QVBoxLayout(panel)
top = QFormLayout()
self.key = QComboBox()
for label, value in lilypond.KEY_SIGNATURES:
self.key.addItem(label, value)
current = self.replacement.key or self.project.key
self.key.setCurrentIndex(
max(0, [v for _, v in lilypond.KEY_SIGNATURES].index(current))
if current in [v for _, v in lilypond.KEY_SIGNATURES]
else 7
)
self.key.currentIndexChanged.connect(self._settings_changed)
top.addRow("Key", self.key)
row = QHBoxLayout()
self.time = QLineEdit(self.replacement.time or self.project.time)
self.time.setFixedWidth(70)
self.time.textChanged.connect(self._settings_changed)
row.addWidget(self.time)
self.print_time = QCheckBox("print it (only the song's first system shows one)")
self.print_time.setChecked(self.replacement.print_time)
self.print_time.toggled.connect(self._settings_changed)
row.addWidget(self.print_time, 1)
top.addRow("Time", row)
# A property of the slice, not of the replacement — the same field the
# main panel shows for a scanned slice — so it survives discarding the
# engraving. Unlike key and time it cannot be inherited from the song.
current = self.state.bars[self.slot]
self.bar = QLineEdit("" if current is None else str(current))
self.bar.setValidator(QIntValidator(1, 9999, self.bar))
self.bar.setFixedWidth(70)
self.bar.setPlaceholderText("none")
self.bar.setToolTip("Printed above the first bar, as a printed score numbers its systems")
self.bar.textChanged.connect(self._bar_changed)
top.addRow("First bar", self.bar)
box.addLayout(top)
voices_label = QLabel("Voices")
voices_label.setStyleSheet(ui.HEADING.replace("QToolButton", "QLabel"))
box.addWidget(voices_label)
self.voice_box = QVBoxLayout()
box.addLayout(self.voice_box)
self.rows: list[VoiceRow] = []
for voice in self.replacement.voices:
self._add_row(voice)
buttons = QHBoxLayout()
add = QPushButton("Add voice")
add.clicked.connect(self._add_voice)
remove = QPushButton("Remove last voice")
remove.clicked.connect(self._remove_voice)
render = QPushButton("Render (Ctrl+↵)")
render.setProperty("role", "primary")
render.clicked.connect(self.render)
drop = QPushButton("Discard replacement")
drop.clicked.connect(self._discard)
for button in (add, remove, render, drop):
buttons.addWidget(button)
box.addLayout(buttons)
self.status = QLabel()
self.status.setWordWrap(True)
box.addWidget(self.status)
# Collapsed: the source is what the form writes for you, so it is for
# checking what a field did, not for working in. Open it and it stays
# open for the life of the window.
raw = section("LilyPond source", box, expanded=False)
self.generated = QPlainTextEdit()
self.generated.setReadOnly(True)
self.generated.setMaximumHeight(220)
self.generated.setStyleSheet(f"color: {ui.GRAPHITE};")
raw.addWidget(self.generated)
self._refresh_source()
return panel
# -- edits ------------------------------------------------------------
def _add_row(self, voice: Voice) -> None:
row = VoiceRow(voice, len(self.rows), self._refresh_source)
self.rows.append(row)
self.voice_box.addWidget(row)
def _add_voice(self) -> None:
clefs = self.project.clefs
index = len(self.replacement.voices)
voice = Voice(clef=clefs[index] if index < len(clefs) else "treble")
self.replacement.voices.append(voice)
self._add_row(voice)
self._refresh_source()
def _remove_voice(self) -> None:
if not self.rows:
return
self.replacement.voices.pop()
row = self.rows.pop()
row.setParent(None)
self._refresh_source()
def _bar_changed(self, text: str) -> None:
self.state.bars[self.slot] = int(text) if text.strip().isdigit() else None
self._refresh_source()
def _settings_changed(self) -> None:
# Set on the song, not the slice: they are song properties in practice,
# and this is what makes the next re-engraved slice open pre-filled.
self.project.key = self.key.currentData()
self.project.time = self.time.text().strip() or "4/4"
self.replacement.key = None
self.replacement.time = None
self.replacement.print_time = self.print_time.isChecked()
self._refresh_source()
def _discard(self) -> None:
self.project.pages[self.page_index].replacements[self.slot] = None
self.accept()
def _source(self) -> str:
return lilypond.generate(
self.replacement, self.project.key, self.project.time, self.state.bars[self.slot]
)
def _refresh_source(self) -> None:
self.generated.setPlainText(self._source())
# -- rendering --------------------------------------------------------
def render(self) -> None:
source = self._source()
self.status.setStyleSheet(f"color: {ui.GRAPHITE};")
self.status.setText("rendering…")
self.repaint()
try:
image = lilypond.render(source)
except lilypond.LilypondError as error:
self.status.setStyleSheet(f"color: {ui.PROOF};")
self.status.setText(str(error)[-600:])
return
# Shown at the original's staff height rather than its native size:
# LilyPond renders ~4300px wide against a ~1500px scan, and matching
# staff heights is what export does anyway — so this is a preview of
# the real thing rather than of an intermediate.
theirs = staff_height(image, 0, image.shape[0])
ours = staff_height(self.original, 0, self.original.shape[0])
if theirs and ours:
k = ours / theirs
image = cv2.resize(image, None, fx=k, fy=k, interpolation=cv2.INTER_AREA)
self.render_label.setPixmap(_pixmap(image))
self.status.setText(f"rendered — {image.shape[1]}×{image.shape[0]}px at the scan's scale")
def closeEvent(self, event) -> None:
replacement = self.project.pages[self.page_index].replacements[self.slot]
if replacement and not any(v.notes.strip() for v in replacement.voices):
# Nothing was written, so leave the slice as a scanned one rather
# than exporting an empty engraving.
self.project.pages[self.page_index].replacements[self.slot] = None
else:
self.project.pages[self.page_index].remember_clefs(self.project, self.slot)
super().closeEvent(event)
noteman_slicer/lilypond.py
+222
View File
@@ -0,0 +1,222 @@
"""Re-engrave a slice with LilyPond, when the scan is past saving.
Optional. LilyPond is a system package rather than a wheel, so its absence
hides the feature and nothing else changes.
The tool renders a tight-cropped PNG and hands it to the ordinary render
pipeline at the trim stage, so a replaced slice flows through staff-height
normalisation, song scale, pad and encode untouched — which is what makes it
sit at the same note size as the scanned systems around it without any manual
scaling.
"""
from __future__ import annotations
import re
import shutil
import subprocess
import tempfile
from pathlib import Path
import cv2
import numpy as np
RENDER_DPI = 600
TIMEOUT_S = 120
# Read off the page by counting accidentals, which is how you actually read a
# key signature. Both names are shown because either identifies the same
# signature; the major spelling is what LilyPond gets, and it prints the same
# accidentals as the relative minor would.
KEY_SIGNATURES: tuple[tuple[str, str], ...] = (
("7♭ — C♭ major / A♭ minor", "ces"),
("6♭ — G♭ major / E♭ minor", "ges"),
("5♭ — D♭ major / B♭ minor", "des"),
("4♭ — A♭ major / F minor", "aes"),
("3♭ — E♭ major / C minor", "ees"),
("2♭ — B♭ major / G minor", "bes"),
("1♭ — F major / D minor", "f"),
("— C major / A minor", "c"),
("1♯ — G major / E minor", "g"),
("2♯ — D major / B minor", "d"),
("3♯ — A major / F♯ minor", "a"),
("4♯ — E major / C♯ minor", "e"),
("5♯ — B major / G♯ minor", "b"),
("6♯ — F♯ major / D♯ minor", "fis"),
("7♯ — C♯ major / A♯ minor", "cis"),
)
# Kaipaava's five-staff system uses all but the alto.
CLEFS: tuple[tuple[str, str], ...] = (
("Treble", "treble"),
("Treble 8 (tenor)", "treble_8"),
("Bass", "bass"),
("Alto", "alto"),
)
# Notes are entered in \relative mode, so only intervals larger than a fourth
# need an octave mark. The reference pitch is the middle of each clef's staff,
# so the first note of a part usually needs no mark either.
RELATIVE_REFERENCE = {
"treble": "c''",
"treble_8": "c'",
"alto": "c'",
"bass": "c",
}
# LilyPond renamed the repeat barlines and silently draws *nothing* for the old
# names — no error, no warning, just a missing repeat that you find on the
# tablet. Every book, every forum answer and every score anyone has typed before
# uses the old ones, so translate them.
_BAR_ALIASES = {
"|:": ".|:",
":|": ":|.",
":|:": ":|.|:",
"||:": ".|:",
":||": ":|.",
":||:": ":|.|:",
}
_BAR = re.compile(r'(\\bar\s*")([^"]*)(")')
def _modernise_bars(notes: str) -> str:
return _BAR.sub(lambda m: m[1] + _BAR_ALIASES.get(m[2], m[2]) + m[3], notes)
_PREAMBLE = """\\version "2.24.0"
\\paper {
indent = 0\\mm
ragged-right = ##f
oddHeaderMarkup = ##f evenHeaderMarkup = ##f
oddFooterMarkup = ##f evenFooterMarkup = ##f
print-page-number = ##f
}
"""
def generate(replacement, key: str, time: str, bar: int | None = None) -> str:
"""Build LilyPond source from a slice's structured replacement.
The time signature is used for spacing and bar checks but not printed
unless asked for: the printed score repeats the key at every system and the
time signature only at the first, so a re-engraved middle slice showing one
would stand out immediately in the scroll.
"""
key = replacement.key or key
time = replacement.time or time
# Bar numbering is a Score property, so it is set once, on the first staff.
# Visible at the beginning of a line and nowhere else — which in a
# one-system slice means exactly one number, above the first bar, the way a
# printed score numbers its systems. The empty bar line is what gives the
# number a line beginning to attach to.
number = ""
if bar:
number = (
f" \\set Score.currentBarNumber = #{int(bar)}\n"
" \\override Score.BarNumber.break-visibility = #'#(#f #f #t)\n"
' \\bar ""\n'
)
staves = []
for voice in replacement.voices:
hide = "" if replacement.print_time else " \\omit Staff.TimeSignature\n"
body = _modernise_bars(voice.notes.strip()) or "s1"
reference = RELATIVE_REFERENCE.get(voice.clef, "c'")
staff = (
" \\new Staff {\n"
f"{hide}"
# Quoted, because an octavated name has to be: unquoted,
# `\clef treble_8` parses as a plain treble clef with a stray "8"
# markup that lands under the first note, and the staff then reads
# an octave off.
f' \\clef "{voice.clef}"\n'
f" \\key {key} \\major\n"
f" \\time {time}\n"
f"{number if not staves else ''}"
f" \\relative {reference} {{ {body} }}\n"
" }\n"
)
if voice.lyrics.strip():
staff += f" \\addlyrics {{ {voice.lyrics.strip()} }}\n"
staves.append(staff)
if not staves:
staves.append(" \\new Staff { s1 }\n")
return (
_PREAMBLE
+ "\\score {\n \\new ChoirStaff <<\n"
+ "".join(staves)
+ " >>\n \\layout { }\n}\n"
)
class LilypondError(RuntimeError):
"""LilyPond refused the source. Carries its diagnostics verbatim."""
def available() -> bool:
return shutil.which("lilypond") is not None
def version() -> str | None:
if not available():
return None
try:
out = subprocess.run(
["lilypond", "--version"], capture_output=True, text=True, timeout=20
)
except (OSError, subprocess.SubprocessError):
return None
return out.stdout.splitlines()[0] if out.stdout else None
def render(source: str, dpi: int = RENDER_DPI) -> np.ndarray:
"""Engrave `source` and return it as a grayscale array, cropped to the ink.
Raises LilypondError with LilyPond's own message on failure — a syntax
error has to be readable without leaving the editor.
"""
if not available():
raise LilypondError("LilyPond is not installed")
with tempfile.TemporaryDirectory(prefix="noteman-slicer-ly-") as workdir:
work = Path(workdir)
(work / "slice.ly").write_text(source, encoding="utf-8")
try:
result = subprocess.run(
[
"lilypond",
"-dcrop=#t",
"-dbackend=cairo",
"--png",
f"-dresolution={dpi}",
"-o",
"out",
"slice.ly",
],
cwd=work,
capture_output=True,
text=True,
timeout=TIMEOUT_S,
)
except subprocess.TimeoutExpired as error:
raise LilypondError(f"LilyPond timed out after {TIMEOUT_S}s") from error
# LilyPond still writes a page when it rejects the source, so the exit
# code has to be checked first — otherwise a broken snippet silently
# becomes a garbage slice.
if result.returncode != 0:
raise LilypondError(result.stderr.strip() or f"exit status {result.returncode}")
# -dcrop writes out.cropped.png; the uncropped page is the fallback if
# a LilyPond build ever stops honouring it.
for name in ("out.cropped.png", "out.png"):
image = work / name
if image.exists():
gray = cv2.imread(str(image), cv2.IMREAD_GRAYSCALE)
if gray is not None:
return gray
raise LilypondError(result.stderr.strip() or result.stdout.strip() or "no output")
noteman_slicer/overlay.py
+55
View File
@@ -0,0 +1,55 @@
"""Debug overlay: what detection proposed, drawn on the page.
The fastest way to judge a detection change, and the tool for working out why
song #40 came out wrong. Kept after release for that reason.
"""
from __future__ import annotations
from pathlib import Path
import cv2
import numpy as np
from .detect import PageDetection
_SYSTEM = (0, 160, 0)
_CUT = (0, 0, 255)
_PROFILE = (220, 120, 0)
_PREVIEW_WIDTH = 1100
def draw(gray: np.ndarray, detection: PageDetection) -> np.ndarray:
"""Straightened page with systems boxed, cuts lined, row profile down the side."""
from .detect import deskew, row_darkness
straight = deskew(gray, detection.skew)
vis = cv2.cvtColor(straight, cv2.COLOR_GRAY2BGR)
h, w = straight.shape
thickness = max(1, w // 700)
profile = row_darkness(straight)
if profile.max() > 0:
scaled = (profile / profile.max() * (w * 0.08)).astype(int)
for y in range(0, h, max(1, h // 900)):
cv2.line(vis, (0, y), (int(scaled[y]), y), _PROFILE, 1)
for i, system in enumerate(detection.systems):
cv2.rectangle(vis, (2, system.top), (w - 3, system.bottom), _SYSTEM, thickness)
label = f"{i + 1}"
if system.staff_height:
label += f" staff {system.staff_height:.0f}px"
cv2.putText(vis, label, (int(w * 0.10), system.top + int(h * 0.02)),
cv2.FONT_HERSHEY_SIMPLEX, w / 1400, _SYSTEM, thickness)
for y in detection.cuts:
cv2.line(vis, (0, y), (w, y), _CUT, thickness)
return vis
def write(gray: np.ndarray, detection: PageDetection, path: Path) -> Path:
vis = draw(gray, detection)
height = int(vis.shape[0] * _PREVIEW_WIDTH / vis.shape[1])
cv2.imwrite(str(path), cv2.resize(vis, (_PREVIEW_WIDTH, height), interpolation=cv2.INTER_AREA))
return path
noteman_slicer/panel.py
+373
View File
@@ -0,0 +1,373 @@
"""Look and feel for the editor: palette, chrome, and two custom controls.
The page already speaks a colour language — red cut lines, a blue content
rectangle, purple marker chips, amber for a re-engraved system. The panel
speaks the same one, from the same constants, so a colour means one thing in
this window rather than two. Everything else is neutral, and the chrome is
dark for the reason photo editors are: the scanned page should be the
brightest object on screen, because it is the thing being judged.
Numbers are set in mono and prose is not. This is a measuring tool; skew,
levels, bar and page numbers are measurements, and they line up in a column
when they are monospaced.
"""
from __future__ import annotations
import numpy as np
from PySide6.QtCore import QRectF, Qt, Signal
from PySide6.QtGui import QBrush, QColor, QFont, QLinearGradient, QPainter, QPen
from PySide6.QtWidgets import QGridLayout, QSizePolicy, QToolButton, QWidget
INK = "#14161a" # window chrome
DESK = "#1d2026" # panel surface
RAISED = "#262a33" # inputs, chips
RULE = "#333844" # hairlines
GRAPHITE = "#8b93a3" # secondary text and section headings
PAPER = "#e6e9f0" # primary text, borrowed from the scan
PROOF = "#dc2828" # cuts
CROP = "#288cdc" # content rectangle, primary action
MARK = "#9638be" # markers
PLATE = "#c87800" # re-engraved
MONO = '"JetBrains Mono", "DejaVu Sans Mono", "Menlo", monospace'
STYLESHEET = f"""
QMainWindow, QDialog {{ background: {INK}; }}
QWidget {{ color: {PAPER}; font-size: 13px; }}
QScrollArea, QScrollArea > QWidget > QWidget {{ background: {DESK}; border: none; }}
QSplitter::handle {{ background: {RULE}; width: 1px; }}
QGraphicsView {{ background: {INK}; border: none; }}
QLabel {{ background: transparent; }}
QLabel[role="hint"] {{ color: {GRAPHITE}; font-size: 12px; }}
QLabel[role="reading"] {{ color: {PAPER}; font-family: {MONO}; font-size: 12px; }}
QLineEdit, QComboBox, QDoubleSpinBox, QListWidget {{
background: {RAISED}; border: 1px solid {RULE}; border-radius: 3px;
padding: 4px 6px; selection-background-color: {CROP};
}}
QLineEdit:focus, QComboBox:focus, QDoubleSpinBox:focus, QListWidget:focus {{
border-color: {CROP};
}}
QLineEdit[role="number"], QDoubleSpinBox {{ font-family: {MONO}; }}
QComboBox::drop-down {{ border: none; width: 18px; }}
QDoubleSpinBox::up-button, QDoubleSpinBox::down-button {{
background: {RULE}; border: none; width: 16px;
}}
QDoubleSpinBox::up-arrow, QDoubleSpinBox::down-arrow {{ width: 7px; height: 7px; }}
QComboBox QAbstractItemView {{
background: {RAISED}; border: 1px solid {RULE}; selection-background-color: {CROP};
}}
QListWidget::item {{ padding: 2px 4px; }}
QListWidget::item:selected {{ background: {MARK}; }}
QPushButton {{
background: {RAISED}; border: 1px solid {RULE}; border-radius: 3px;
padding: 6px 12px;
}}
QPushButton:hover {{ border-color: {GRAPHITE}; }}
QPushButton:pressed {{ background: {RULE}; }}
QPushButton:disabled {{ color: {RULE}; }}
QPushButton:focus {{ border-color: {CROP}; }}
QPushButton[role="primary"] {{
background: {CROP}; border-color: {CROP}; color: #ffffff;
font-weight: 600; padding: 9px 12px;
}}
QPushButton[role="primary"]:hover {{ background: #3a9de8; }}
QScrollBar:vertical {{ background: {DESK}; width: 10px; margin: 0; }}
QScrollBar:horizontal {{ background: {DESK}; height: 10px; margin: 0; }}
QScrollBar::handle {{ background: {RULE}; border-radius: 5px; min-height: 30px; }}
QScrollBar::handle:hover {{ background: {GRAPHITE}; }}
QScrollBar::add-line, QScrollBar::sub-line {{ height: 0; width: 0; }}
QScrollBar::add-page, QScrollBar::sub-page {{ background: transparent; }}
QCheckBox {{ spacing: 7px; }}
QCheckBox::indicator {{
width: 14px; height: 14px; border: 1px solid {RULE};
border-radius: 3px; background: {RAISED};
}}
QCheckBox::indicator:checked {{ background: {CROP}; border-color: {CROP}; }}
QCheckBox::indicator:hover {{ border-color: {GRAPHITE}; }}
QStatusBar {{ background: {INK}; color: {GRAPHITE}; }}
QToolTip {{ background: {RAISED}; color: {PAPER}; border: 1px solid {RULE}; padding: 4px; }}
"""
HEADING = f"""
QToolButton {{
border: none; background: transparent; text-align: left;
color: {GRAPHITE}; font-size: 11px; font-weight: 700;
letter-spacing: 1.4px; padding: 10px 0 5px 0;
}}
QToolButton:hover {{ color: {PAPER}; }}
"""
def mono(size: int = 12, weight: int = QFont.Normal) -> QFont:
font = QFont("JetBrains Mono", size, weight)
font.setStyleHint(QFont.Monospace)
return font
class Rule(QWidget):
"""A hairline between sections. Structure the eye can follow without boxes."""
def __init__(self) -> None:
super().__init__()
self.setFixedHeight(1)
self.setStyleSheet(f"background: {RULE};")
class PageRail(QWidget):
"""One chip per page, each carrying its slice count.
Replaces a ◀ 1/6 ▶ stepper. The song *is* a sequence of pages with a
number of systems on each, and seeing that sequence is how you notice the
page where detection found one slice where the others found three — the
failure this tool actually produces.
"""
picked = Signal(int)
COLUMNS = 7 # ponytail: fixed, sized for the panel's minimum width
def __init__(self) -> None:
super().__init__()
self.buttons: list[QToolButton] = []
self.grid = QGridLayout(self)
self.grid.setContentsMargins(0, 0, 0, 0)
self.grid.setSpacing(4)
self.setSizePolicy(QSizePolicy.Preferred, QSizePolicy.Fixed)
def build(self, counts: list[int], current: int) -> None:
while self.buttons:
chip = self.buttons.pop()
self.grid.removeWidget(chip)
chip.deleteLater()
for i, count in enumerate(counts):
chip = QToolButton()
chip.setText(f"{i + 1}\n{count}")
chip.setFont(mono(11))
chip.setFixedSize(34, 38)
chip.setCursor(Qt.PointingHandCursor)
chip.setToolTip(f"Page {i + 1} — {count} slice{'s' if count != 1 else ''}")
chip.setStyleSheet(self._chip_style(i == current))
chip.clicked.connect(lambda _=False, n=i: self.picked.emit(n))
self.grid.addWidget(chip, i // self.COLUMNS, i % self.COLUMNS)
self.buttons.append(chip)
self.grid.setColumnStretch(self.COLUMNS, 1)
@staticmethod
def _chip_style(current: bool) -> str:
return (
f"QToolButton {{ background: {'#12405f' if current else RULE};"
f" border: 1px solid {CROP if current else '#454b59'}; border-radius: 3px;"
f" color: {PAPER if current else GRAPHITE}; }}"
f"QToolButton:hover {{ border-color: {PAPER}; color: {PAPER}; }}"
)
class LevelsBar(QWidget):
"""The scan's own ink distribution, with the black and white points on it.
The signature control of this window, and the one place worth spending
pixels: getting levels wrong is the single mistake that cannot be seen
until the bundle is on the tablet, and two anonymous sliders give no reason
to move either one. Here the paper hump and the ink hump are visible, the
handles sit on them, and the strip underneath shows the tone ramp that
results — grey ink looks grey right there.
"""
changed = Signal(int, int)
RAMP = 14 # height of the tone strip under the histogram
GRAB = 7
def __init__(self) -> None:
super().__init__()
self.hist = np.zeros(256)
self.black, self.white = 0, 255
self._drag: str | None = None
self.setMinimumHeight(96)
self.setMouseTracking(True)
self.setCursor(Qt.SizeHorCursor)
self.setFocusPolicy(Qt.StrongFocus)
def set_page(self, gray: np.ndarray) -> None:
counts = np.bincount(gray.ravel(), minlength=256).astype(float)
# Square root, clipped to the tallest bin that is not the paper spike.
# Linear buries the ink hump under a spike two orders of magnitude
# taller; log flattens everything into one slab. This keeps both humps
# shaped like humps, which is the whole point of showing them.
scale = np.sqrt(counts)
ceiling = np.partition(scale, -3)[-3] or scale.max() or 1.0
self.hist = np.clip(scale / ceiling, 0, 1)
self.update()
def set_levels(self, black: int, white: int) -> None:
self.black, self.white = black, white
self.update()
# -- painting ---------------------------------------------------------
def _x(self, value: int) -> float:
return value / 255 * (self.width() - 1)
def paintEvent(self, event) -> None:
p = QPainter(self)
p.setRenderHint(QPainter.Antialiasing)
w, h = self.width(), self.height()
top = h - self.RAMP - 10
p.fillRect(0, 0, w, top, QColor(INK))
p.setPen(Qt.NoPen)
p.setBrush(QColor("#5f7d99"))
for value in range(256):
bar = self.hist[value] * (top - 4)
p.drawRect(QRectF(self._x(value), top - bar, max(w / 256, 1.0), bar))
# What is clipped away, dimmed at both ends.
p.setBrush(QColor(20, 22, 26, 170))
p.drawRect(QRectF(0, 0, self._x(self.black), top))
p.drawRect(QRectF(self._x(self.white), 0, w - self._x(self.white), top))
ramp = QLinearGradient(self._x(self.black), 0, self._x(self.white), 0)
ramp.setColorAt(0.0, QColor(0, 0, 0))
ramp.setColorAt(1.0, QColor(255, 255, 255))
p.setBrush(QBrush(ramp))
p.drawRect(QRectF(0, h - self.RAMP, w, self.RAMP))
p.fillRect(QRectF(0, h - self.RAMP, self._x(self.black), self.RAMP), QColor(0, 0, 0))
p.fillRect(
QRectF(self._x(self.white), h - self.RAMP, w - self._x(self.white), self.RAMP),
QColor(255, 255, 255),
)
for value, colour in ((self.black, QColor(PAPER)), (self.white, QColor(CROP))):
x = self._x(value)
p.setPen(QPen(colour, 2))
p.drawLine(QRectF(x, 0, 0, h).topLeft(), QRectF(x, 0, 0, h).bottomLeft())
p.setPen(Qt.NoPen)
p.setBrush(colour)
p.drawEllipse(QRectF(x - 4, top + 1, 8, 8))
# Readouts inside the histogram, not on the tone strip: white text on
# the pale end of that ramp is unreadable exactly when the white point
# is where you most need to read it.
p.setFont(mono(10))
p.setPen(QColor(PAPER))
p.drawText(
QRectF(5, 2, w - 10, 16), Qt.AlignLeft | Qt.AlignVCenter, f"black {self.black}"
)
p.setPen(QColor(CROP))
p.drawText(
QRectF(5, 2, w - 10, 16), Qt.AlignRight | Qt.AlignVCenter, f"white {self.white}"
)
# -- interaction ------------------------------------------------------
def _nearest(self, x: float) -> str:
return "black" if abs(x - self._x(self.black)) <= abs(x - self._x(self.white)) else "white"
def mousePressEvent(self, event) -> None:
self._drag = self._nearest(event.position().x())
self.mouseMoveEvent(event)
def mouseMoveEvent(self, event) -> None:
if not self._drag:
return
value = int(round(event.position().x() / max(self.width() - 1, 1) * 255))
value = min(255, max(0, value))
if self._drag == "black":
self.black = min(value, self.white - 1)
else:
self.white = max(value, self.black + 1)
self.update()
self.changed.emit(self.black, self.white)
def mouseReleaseEvent(self, event) -> None:
self._drag = None
def keyPressEvent(self, event) -> None:
step = {Qt.Key_Left: -1, Qt.Key_Right: 1}.get(event.key())
if step is None:
return super().keyPressEvent(event)
# Shift picks the white point, so the whole control is reachable from
# the keyboard without a second focus stop.
if event.modifiers() & Qt.ShiftModifier:
self.white = min(255, max(self.black + 1, self.white + step))
else:
self.black = max(0, min(self.white - 1, self.black + step))
self.update()
self.changed.emit(self.black, self.white)
def keycap(text: str) -> str:
"""A key name as inline HTML, for the shortcut list."""
return (
f'<span style="font-family:{MONO}; background:{RAISED}; color:{PAPER};'
f' border:1px solid {RULE}; padding:1px 4px;">{text}</span>'
)
SHORTCUTS = [
("Double-click", "add a cut"),
("Drag", "move a cut"),
("Ctrl-click", "add a vertex"),
("Right-click", "delete a cut or vertex"),
("D", "discard the selected slice"),
("Shift-double-click", "re-engrave a slice"),
("PgUp / PgDn", "change page"),
("Ctrl+S", "save"),
]
def shortcut_html() -> str:
rows = "".join(
f"<tr><td style='padding:2px 10px 2px 0'>{keycap(k)}</td>"
f"<td style='color:{GRAPHITE}'>{v}</td></tr>"
for k, v in SHORTCUTS
)
return f"<table cellspacing='0'>{rows}</table>"
def demo() -> None:
"""Self-check: the histogram and handles behave without a real page."""
from PySide6.QtWidgets import QApplication
app = QApplication.instance() or QApplication([])
bar = LevelsBar()
bar.resize(300, 96)
bar.set_page(np.array([[10, 10, 250, 250, 250]], np.uint8))
assert bar.hist[250] == 1.0 and 0 < bar.hist[10] <= 1.0, bar.hist[[10, 250]]
assert bar.hist[128] == 0.0, "an empty bin draws nothing"
bar.set_levels(40, 200)
seen: list[tuple[int, int]] = []
bar.changed.connect(lambda b, w: seen.append((b, w)))
bar._drag = "white"
bar.white = 30 # a drag past the black point must not invert the ramp
bar.set_levels(40, 200)
bar.keyPressEvent(_Key(Qt.Key_Left, Qt.NoModifier))
assert bar.black == 39 and seen[-1] == (39, 200), (bar.black, seen)
bar.keyPressEvent(_Key(Qt.Key_Right, Qt.ShiftModifier))
assert bar.white == 201, bar.white
bar.grab() # paints; raises if the painter path is wrong
assert PageRail()._chip_style(True) != PageRail._chip_style(False)
del app
print("ok")
class _Key:
def __init__(self, key, modifiers):
self._key, self._mod = key, modifiers
def key(self):
return self._key
def modifiers(self):
return self._mod
if __name__ == "__main__":
demo()
noteman_slicer/pdf.py
+118
View File
@@ -0,0 +1,118 @@
"""PDF input: classify a score source and hand back page rasters.
Two source types, never mixed within one PDF (docs/spec.md):
raster — a scan; every page carries one full-page image, and *that image
is the scan*. It is extracted at its native resolution rather
than re-rendered: real scans in this corpus run ~200 DPI, and
re-rendering at 600 would triple the pixel count for no detail.
vector — an engraving; nothing to extract, so the page is rendered.
"""
from __future__ import annotations
from dataclasses import dataclass
from enum import Enum
from pathlib import Path
import numpy as np
import pymupdf
VECTOR_RENDER_DPI = 600
# An image covering at least this fraction of the page is the page's scan
# rather than an illustration sitting on an engraving.
_FULL_PAGE_AREA = 0.5
class SourceType(Enum):
RASTER = "raster"
VECTOR = "vector"
@dataclass
class Source:
path: Path
doc: pymupdf.Document
type: SourceType
detected: SourceType
render_dpi: int = VECTOR_RENDER_DPI
@property
def overridden(self) -> bool:
"""True when the user's choice disagrees with detection."""
return self.type is not self.detected
def __len__(self) -> int:
return len(self.doc)
def close(self) -> None:
self.doc.close()
def _full_page_image(page: pymupdf.Page) -> int | None:
"""xref of the image covering this page, or None."""
page_area = abs(page.rect.get_area())
if page_area <= 0:
return None
# full=True is required, or get_image_bbox rejects the item.
for item in page.get_images(full=True):
try:
bbox = pymupdf.Rect(page.get_image_bbox(item))
except ValueError:
continue
if abs(bbox.get_area()) >= page_area * _FULL_PAGE_AREA:
return item[0]
return None
def classify(doc: pymupdf.Document) -> SourceType:
"""Detection only — the caller confirms with the user (ADR 0004)."""
scanned = sum(_full_page_image(page) is not None for page in doc)
return SourceType.RASTER if scanned * 2 > len(doc) else SourceType.VECTOR
def open_source(path: str | Path, source_type: SourceType | None = None) -> Source:
"""Open a PDF. `source_type` overrides detection; it never silently wins."""
path = Path(path)
doc = pymupdf.open(path)
detected = classify(doc)
return Source(path=path, doc=doc, type=source_type or detected, detected=detected)
def page_raster(source: Source, index: int) -> np.ndarray:
"""One page as a grayscale array, at the resolution the pipeline should work at."""
page = source.doc[index]
if source.type is SourceType.RASTER:
xref = _full_page_image(page)
if xref is not None:
# Pixmap(doc, xref) rather than decoding extract_image() bytes:
# MuPDF handles JBIG2 and CCITT, which no image library will.
pix = pymupdf.Pixmap(source.doc, xref)
# The embedded image is in its own orientation, not the page's: a
# scanner that fed the sheet sideways stores it landscape and the
# PDF sets /Rotate so viewers turn it upright. Extracting by xref
# bypasses that, so apply it here — otherwise every system runs
# down the page and detection finds nothing.
return _rotate(_to_gray(pix), page.rotation)
# A scanned PDF whose page has no embedded image (a blank, or a
# cover typeset in vector). Rendering is the only option left.
return _to_gray(page.get_pixmap(dpi=source.render_dpi, colorspace=pymupdf.csGRAY))
def _rotate(gray: np.ndarray, degrees: int) -> np.ndarray:
"""Turn a page raster clockwise by a multiple of 90°, as /Rotate means it.
ponytail: quarter turns only. A page rotated by anything else would need
resampling, and no scanner produces one.
"""
turns = round(degrees / 90) % 4
return np.ascontiguousarray(np.rot90(gray, -turns)) if turns else gray
def _to_gray(pix: pymupdf.Pixmap) -> np.ndarray:
if pix.alpha or pix.colorspace is None or pix.colorspace.n != 1:
pix = pymupdf.Pixmap(pymupdf.csGRAY, pix)
return np.frombuffer(pix.samples, dtype=np.uint8).reshape(pix.height, pix.width)
noteman_slicer/pdfopt.py
+172
View File
@@ -0,0 +1,172 @@
"""Optional shrinking of the original PDF carried in a bundle.
Scanned scores are usually black ink on white paper stored as 8-bit greyscale
or RGB, which costs several times what the same page costs as a bilevel image.
Converting them is worth 7–9× on a real corpus.
Two things it must not do, both found by looking at output rather than at
numbers:
* A page that is genuinely coloured — cover artwork — loses its artwork.
* A scan too coarse to have more than about one pixel per staff line comes
back with the staff lines broken.
Both are detectable before converting, so both are skipped. Everything skipped
is reported, so a caller can say what was left alone and why.
This affects only the archival copy of the score. Slices are cut from the
original before any of this and are unchanged either way.
"""
from __future__ import annotations
from dataclasses import dataclass, field
import cv2
import numpy as np
import pymupdf
# Below this many pixels per inch as the image is *placed on the page*, staff
# lines are about a pixel wide and thresholding breaks them. Measured against a
# corpus where the one failure sat at ~115 DPI and the successes at 260+.
MIN_DPI = 200
# An image is "coloured" when this share of sampled pixels are off-grey by
# more than _CHROMA. The two populations are far apart: measured on a corpus,
# cover artwork sits at 44% while a greyscale scan's sensor tint reaches 3%.
# Ten percent sits in the gap with room on both sides.
_CHROMA = 24
_COLOUR_SHARE = 0.10
_BLOCK = 31 # adaptive threshold window
_OFFSET = 15
@dataclass
class Report:
before: int = 0
after: int = 0
converted: int = 0
skipped: dict[str, int] = field(default_factory=dict)
@property
def ratio(self) -> float:
return self.after / self.before if self.before else 1.0
def skip(self, reason: str) -> None:
self.skipped[reason] = self.skipped.get(reason, 0) + 1
def summary(self) -> str:
if not self.converted:
return "nothing to optimise — every image is already bilevel, coloured or too coarse"
parts = [
f"{self.before / 1024:.0f} KB → {self.after / 1024:.0f} KB "
f"({self.ratio * 100:.0f}%), {self.converted} images converted"
]
for reason, count in sorted(self.skipped.items()):
parts.append(f"{count} left alone: {reason}")
return "\n".join(parts)
def _is_coloured(image: np.ndarray) -> bool:
if image.ndim != 3 or image.shape[2] < 3:
return False
sample = image[::4, ::4, :3].astype(np.int16)
spread = sample.max(axis=2) - sample.min(axis=2)
return float((spread > _CHROMA).mean()) > _COLOUR_SHARE
def _placed_dpi(page: pymupdf.Page, item, width: int) -> float:
"""Pixels per inch of an image as it appears on the page.
Not the pixel count: a page split into tiles has small images at a high
resolution, and a full-page image can be large yet coarse.
"""
try:
bbox = pymupdf.Rect(page.get_image_bbox(item))
except (ValueError, RuntimeError):
return float("inf")
inches = abs(bbox.width) / 72.0
return width / inches if inches > 0 else float("inf")
def optimise(doc: pymupdf.Document, source_bytes: int) -> tuple[bytes, Report]:
"""Return the optimised PDF and a report of what was done.
`doc` is modified in place, so pass a copy or reopen afterwards.
"""
report = Report(before=source_bytes)
for page in doc:
for item in page.get_images(full=True):
xref = item[0]
info = doc.extract_image(xref)
if info.get("bpc") == 1:
report.skip("already bilevel")
continue
if _placed_dpi(page, item, info["width"]) < MIN_DPI:
report.skip(f"below {MIN_DPI} DPI, staff lines would break")
continue
raw = cv2.imdecode(np.frombuffer(info["image"], np.uint8), cv2.IMREAD_UNCHANGED)
if raw is None:
report.skip("unreadable encoding")
continue
if _is_coloured(raw):
report.skip("coloured artwork")
continue
gray = cv2.cvtColor(raw, cv2.COLOR_BGR2GRAY) if raw.ndim == 3 else raw
bilevel = cv2.adaptiveThreshold(
gray, 255, cv2.ADAPTIVE_THRESH_MEAN_C, cv2.THRESH_BINARY, _BLOCK, _OFFSET
)
ok, buffer = cv2.imencode(".png", bilevel, [cv2.IMWRITE_PNG_COMPRESSION, 9])
if not ok:
report.skip("re-encoding failed")
continue
try:
page.replace_image(xref, stream=buffer.tobytes())
except (ValueError, RuntimeError):
report.skip("could not be replaced")
continue
report.converted += 1
data = doc.tobytes(garbage=4, deflate=True, clean=True)
# Never hand back something larger than what came in.
if len(data) >= source_bytes:
report.after = source_bytes
report.converted = 0
report.skip("no saving available")
return b"", report
report.after = len(data)
return data, report
def preview(original: pymupdf.Document, optimised: pymupdf.Document, dpi: int = 260):
"""A stacked before/after crop of the first page, for eyeballing the result.
The numbers cannot show the failure this guards against — a broken staff
line is obvious at a glance and invisible in a byte count.
"""
rect = original[0].rect
clip = pymupdf.Rect(
rect.x0 + rect.width * 0.08,
rect.y0 + rect.height * 0.20,
rect.x0 + rect.width * 0.58,
rect.y0 + rect.height * 0.33,
)
def render(doc: pymupdf.Document) -> np.ndarray:
pix = doc[0].get_pixmap(dpi=dpi, clip=clip)
image = np.frombuffer(pix.samples, np.uint8).reshape(pix.height, pix.width, pix.n)
return image[:, :, :3] if pix.n >= 3 else cv2.cvtColor(image[:, :, 0], cv2.COLOR_GRAY2BGR)
before, after = render(original), render(optimised)
h = min(before.shape[0], after.shape[0])
w = min(before.shape[1], after.shape[1])
divider = np.full((4, w, 3), 128, np.uint8)
return np.vstack([before[:h, :w], divider, after[:h, :w]])
noteman_slicer/project.py
+499
View File
@@ -0,0 +1,499 @@
"""Project state: everything the human decided, on disk beside the PDF.
The bundle is generated from this, so export is a pure function of the project
plus the PDF. That buys crash safety, resume across sessions, and re-export —
change the width cap or fix one cut and every song regenerates without
repeating any human work.
All geometry is stored in **normalised page coordinates** (0–1 of the deskewed
page), so the file is independent of DPI and of which renderer produced it.
"""
from __future__ import annotations
import hashlib
import json
from dataclasses import dataclass, field
from pathlib import Path
from statistics import median
from .detect import PageDetection
FORMAT_VERSION = 1
SUFFIX = ".slicer.json"
Point = tuple[float, float]
@dataclass
class Cut:
"""A boundary splitting one slice into two, spanning the page left to right.
A polyline, not a line. Two points is the ordinary straight case; extra
vertices handle a section label printed in the left margin at the same
height as the previous system's lyrics, where no horizontal line separates
the two (see docs/spec.md).
"""
points: list[Point]
@classmethod
def straight(cls, y: float) -> Cut:
return cls([(0.0, y), (1.0, y)])
@property
def straight_y(self) -> float | None:
"""The single y of a straight cut, or None if it steps."""
ys = {y for _, y in self.points}
return self.points[0][1] if len(ys) == 1 else None
def y_at(self, x: float) -> float:
"""Height of the boundary at a horizontal position."""
pts = self.points
if x <= pts[0][0]:
return pts[0][1]
for (x0, y0), (x1, y1) in zip(pts, pts[1:]):
if x <= x1:
if x1 == x0:
return y1
return y0 + (y1 - y0) * (x - x0) / (x1 - x0)
return pts[-1][1]
@property
def lowest(self) -> float:
return max(y for _, y in self.points)
@property
def highest(self) -> float:
return min(y for _, y in self.points)
# noteman's enum, verbatim. Real coupling between two repos: adding a type
# means changing both. Order is the order they appear in the editor's picker.
MARKER_TYPES = (
"rehearsal_letter",
"section_label",
"segno",
"coda",
"fine",
"repeat_start",
"repeat_end",
"volta",
"to_coda",
"ds_al_coda",
"ds_al_fine",
"dc_al_coda",
"dc_al_fine",
"generic_jump",
)
# The types that carry free text.
LABELLED_TYPES = frozenset({"rehearsal_letter", "section_label", "volta"})
# The types that send the reader elsewhere. Every one stores its target
# explicitly rather than resolving by type at read time, so the bundle is
# self-describing and a score with two codas simply works.
JUMP_TYPES = frozenset(
{"to_coda", "ds_al_coda", "ds_al_fine", "dc_al_coda", "dc_al_fine", "generic_jump"}
)
@dataclass
class Marker:
"""A semantic tag on a slice, used by noteman's navigation."""
type: str
label: str | None = None
# (page, slot) of the target slice, for jump sources. Positional like the
# slices themselves; resolved to a bundle index at export.
destination: tuple[int, int] | None = None
@property
def is_jump(self) -> bool:
return self.type in JUMP_TYPES
def describe(self) -> str:
"""For the marker list and the badge drawn on the page — never the wire.
A musician reads "D.S. al coda" off the score, not `ds_al_coda`.
"""
text = self.type.replace("_", " ").capitalize()
if self.label:
text += f" “{self.label}”"
if self.destination:
text += f" → p{self.destination[0] + 1}s{self.destination[1] + 1}"
return text
@dataclass
class Voice:
"""One staff of a re-engraved system.
`notes` and `lyrics` are raw LilyPond, so slurs, dynamics, tuplets and the
`\\laissezVibrer` / `\\repeatTie` idiom for ties crossing a slice boundary
all work without the form knowing anything about them.
"""
clef: str = "treble"
notes: str = ""
lyrics: str = ""
@dataclass
class Replacement:
"""A system engraved with LilyPond in place of the scanned one.
Key and time are per song in practice — Kaipaava is 4♭ and 4/4 from first
system to last — so they live on the project and are only set here when a
slice genuinely differs.
"""
voices: list[Voice] = field(default_factory=list)
key: str | None = None
time: str | None = None
# The printed score repeats the key signature at every system but not the
# time signature, so a re-engraved middle slice must not show one.
print_time: bool = False
@dataclass
class Page:
"""One page's decisions. `cuts` are ordered top to bottom."""
skew: float = 0.0
cuts: list[Cut] = field(default_factory=list)
discards: list[bool] = field(default_factory=lambda: [False])
# One list per slice, parallel to `discards`.
markers: list[list[Marker]] = field(default_factory=lambda: [[]])
# A re-engraved system per slice, when the scan is past saving. None for
# the ordinary case, which is nearly all of them.
replacements: list[Replacement | None] = field(default_factory=lambda: [None])
# The measure each slice starts at, when it is known. A property of the
# slice rather than of a replacement: a scanned system has a bar number
# printed on it just as an engraved one does, and noteman wants to say
# "from bar 33" about either.
bars: list[int | None] = field(default_factory=lambda: [None])
content_rect: tuple[float, float, float, float] | None = None
levels: tuple[int, int] | None = None
@property
def slice_count(self) -> int:
return len(self.cuts) + 1
def bounds(self, index: int) -> tuple[Cut | None, Cut | None]:
"""The cuts above and below a slice; None means the page edge."""
above = self.cuts[index - 1] if index > 0 else None
below = self.cuts[index] if index < len(self.cuts) else None
return above, below
def add_cut(self, cut: Cut) -> int:
"""Insert a cut, splitting the slice it lands in. Returns its index."""
y = cut.points[0][1]
index = sum(1 for c in self.cuts if c.points[0][1] < y)
self.cuts.insert(index, cut)
# The split slice keeps its flag on both halves. Its markers stay with
# the upper half: a marker sits on a printed symbol, and splitting a
# slice cannot say which side that symbol landed on — leaving them put
# is at least predictable, and moving one is a click.
self.discards.insert(index, self.discards[index])
self.markers.insert(index + 1, [])
self.replacements.insert(index + 1, None)
# The upper half keeps the number: it still starts where the slice did.
# What bar the new lower half starts at needs counting, which is the
# user's job.
self.bars.insert(index + 1, None)
return index
def remove_cut(self, index: int) -> None:
"""Drop a cut, merging the two slices it separated."""
self.cuts.pop(index)
merged = self.discards[index] and self.discards[index + 1]
self.discards.pop(index + 1)
self.discards[index] = merged
self.markers[index].extend(self.markers.pop(index + 1))
# Two engraved halves cannot be merged, so the upper one wins.
below = self.replacements.pop(index + 1)
self.replacements[index] = self.replacements[index] or below
# The merged slice starts where the upper half did.
self.bars.pop(index + 1)
def remember_clefs(self, project: Project, slot: int) -> None:
"""Carry this slice's clefs forward as the song's defaults."""
replacement = self.replacements[slot]
if replacement and replacement.voices:
project.clefs = [v.clef for v in replacement.voices]
@dataclass
class Project:
source: Path
source_hash: str
pages: list[Page]
content_rect: tuple[float, float, float, float] = (0.0, 0.0, 1.0, 1.0)
levels: tuple[int, int] = (0, 255)
metadata: dict[str, str] = field(default_factory=dict)
# Engraving defaults for the song. Key and time are set once and inherited
# by every replacement; `clefs` remembers what each voice position was last
# given, so the second re-engraved system in a song opens already filled in.
key: str = "c"
time: str = "4/4"
clefs: list[str] = field(default_factory=list)
# Shrink the archival PDF carried in the bundle by converting its scanned
# pages to bilevel. Off by default: it is lossy on the copy kept for
# printing, and on some scans it breaks staff lines.
optimise_pdf: bool = False
path: Path | None = None
# Set once the song has been exported. A project is spent at that point:
# opening the PDF again starts a fresh session from detection rather than
# resuming, so a re-cut never begins from stale decisions. `--resume`
# overrides it when the old state really is wanted.
exported: bool = False
# -- geometry helpers -------------------------------------------------
def page_content_rect(self, index: int) -> tuple[float, float, float, float]:
return self.pages[index].content_rect or self.content_rect
def page_levels(self, index: int) -> tuple[int, int]:
return self.pages[index].levels or self.levels
def kept_slices(self) -> list[tuple[int, int]]:
"""(page, slice) of every slice that will be exported, in song order."""
return [
(p, s)
for p, page in enumerate(self.pages)
for s in range(page.slice_count)
if not page.discards[s]
]
# -- persistence ------------------------------------------------------
@classmethod
def from_detection(
cls, source: Path, detections: list[PageDetection], heights: list[int]
) -> Project:
"""Seed a project from detection. Every value here is a suggestion.
Detection emits cuts only *between* systems, so a page would otherwise
have exactly as many slices as it has systems, with the header and
footer inside the first and last. The boundary cuts that isolate them —
and the discard flags that drop them — are a slicing decision, not a
detection result, so they are added here.
"""
pages = []
for detection, height in zip(detections, heights):
ys = list(detection.cuts)
leading = trailing = False
if detection.systems:
first, last = detection.systems[0], detection.systems[-1]
if first.top > 0:
ys.insert(0, first.top // 2)
leading = True
if last.bottom < height:
ys.append((last.bottom + height) // 2)
trailing = True
discards = [False] * (len(ys) + 1)
if leading:
discards[0] = True
if trailing:
discards[-1] = True
pages.append(
Page(
skew=detection.skew,
cuts=[Cut.straight(y / height) for y in ys],
discards=discards,
markers=[[] for _ in discards],
replacements=[None] * len(discards),
bars=[None] * len(discards),
# Per page, not per song: scans drift, so the margin junk
# sits in a different place on each one.
content_rect=detection.content,
)
)
# Levels per song, not per page: a scanner's contrast does not change
# between sheets, and one pair of sliders for the whole song is what a
# user actually wants to nudge. The median keeps a near-blank page —
# where the ink/paper split is guesswork — from setting them.
proposals = [d.levels for d in detections] or [(0, 255)]
levels = (
int(median(b for b, _ in proposals)),
int(median(w for _, w in proposals)),
)
return cls(
source=source, source_hash=hash_file(source), pages=pages, levels=levels
)
def save(self, path: Path | None = None) -> Path:
"""Atomic write, so a crash mid-save cannot destroy the previous state."""
target = Path(path or self.path or default_path(self.source))
payload = {
"v": FORMAT_VERSION,
"source": self.source.name,
"source_hash": self.source_hash,
"exported": self.exported,
"content_rect": list(self.content_rect),
"levels": list(self.levels),
"metadata": self.metadata,
"key": self.key,
"time": self.time,
"clefs": self.clefs,
"optimise_pdf": self.optimise_pdf,
"pages": [
{
"skew": page.skew,
"cuts": [[list(p) for p in cut.points] for cut in page.cuts],
"discards": page.discards,
"markers": [
[
{
"type": m.type,
**({"label": m.label} if m.label else {}),
**(
{"destination": list(m.destination)}
if m.destination
else {}
),
}
for m in slot
]
for slot in page.markers
],
"replacements": [
None
if r is None
else {
"voices": [
{"clef": v.clef, "notes": v.notes, "lyrics": v.lyrics}
for v in r.voices
],
**({"key": r.key} if r.key else {}),
**({"time": r.time} if r.time else {}),
**({"print_time": True} if r.print_time else {}),
}
for r in page.replacements
],
"bars": page.bars,
"content_rect": list(page.content_rect) if page.content_rect else None,
"levels": list(page.levels) if page.levels else None,
}
for page in self.pages
],
}
tmp = target.with_suffix(target.suffix + ".tmp")
tmp.write_text(json.dumps(payload, indent=2, ensure_ascii=False))
tmp.replace(target)
self.path = target
return target
@classmethod
def load(cls, path: Path, source: Path | None = None) -> Project:
path = Path(path)
data = json.loads(path.read_text())
if data.get("v") != FORMAT_VERSION:
raise ValueError(f"unsupported project version {data.get('v')!r}")
pdf = Path(source) if source else path.parent / data["source"]
pages = [
Page(
skew=page["skew"],
cuts=[Cut([tuple(p) for p in cut]) for cut in page["cuts"]],
discards=page["discards"],
markers=[
[
Marker(
type=m["type"],
label=m.get("label"),
destination=tuple(m["destination"]) if m.get("destination") else None,
)
for m in slot
]
for slot in page.get("markers", [[] for _ in page["discards"]])
],
replacements=[
# A bare string is the short-lived raw-source form, which
# never shipped: dropped rather than migrated, so the rest
# of the project still opens.
None
if not isinstance(r, dict)
else Replacement(
voices=[
Voice(
clef=v.get("clef", "treble"),
notes=v.get("notes", ""),
lyrics=v.get("lyrics", ""),
)
for v in r.get("voices", [])
],
key=r.get("key"),
time=r.get("time"),
print_time=r.get("print_time", False),
)
for r in page.get("replacements", [None] * len(page["discards"]))
],
bars=page.get(
"bars",
# Before bar numbers were a property of the slice they lived
# on the replacement, so an engraved slice is where an older
# project keeps one.
[
r.get("bar") if isinstance(r, dict) else None
for r in page.get("replacements", [None] * len(page["discards"]))
],
),
content_rect=tuple(page["content_rect"]) if page["content_rect"] else None,
levels=tuple(page["levels"]) if page["levels"] else None,
)
for page in data["pages"]
]
return cls(
source=pdf,
source_hash=data["source_hash"],
pages=pages,
content_rect=tuple(data["content_rect"]),
levels=tuple(data["levels"]),
metadata=data.get("metadata", {}),
path=path,
exported=data.get("exported", False),
key=data.get("key", "c"),
time=data.get("time", "4/4"),
clefs=data.get("clefs", []),
optimise_pdf=data.get("optimise_pdf", False),
)
def source_changed(self) -> bool:
"""True when the PDF no longer matches what these decisions were made on."""
return self.source.exists() and hash_file(self.source) != self.source_hash
def open_project(source, *, resume: bool = False) -> Project:
"""The project for a PDF: resumed, or a fresh session from detection.
A project that has been exported is spent. Opening the PDF again starts
over from detection rather than resuming, so a re-cut never inherits stale
decisions. `resume` overrides that when the old state really is wanted.
"""
from .detect import detect_page
from .pdf import page_raster
path = default_path(source.path)
if path.exists():
existing = Project.load(path)
if resume or not existing.exported:
return existing
detections, heights = [], []
for i in range(len(source)):
gray = page_raster(source, i)
detections.append(detect_page(gray))
heights.append(gray.shape[0])
return Project.from_detection(source.path, detections, heights)
def default_path(source: Path) -> Path:
return Path(source).with_suffix(SUFFIX)
def hash_file(path: Path) -> str:
return hashlib.sha256(Path(path).read_bytes()).hexdigest()
noteman_slicer/render.py
+252
View File
@@ -0,0 +1,252 @@
"""Render project state into finished slice images.
load raster → deskew → levels → content rect → cut → discard
→ trim → scale → pad → ink→alpha → encode
The order is not arbitrary. Levels runs before anything geometric so the trim
bounding box is computed on the image that actually ships; the content
rectangle runs before cutting so margin junk never enters a slice; and trim
runs before scale because the scale factor derives from the widest *trimmed*
slice.
Output is final — nothing downstream reprocesses it (ADR 0001).
"""
from __future__ import annotations
from dataclasses import dataclass
import cv2
import numpy as np
from . import lilypond
from .detect import deskew, staff_height
from .pdf import Source, page_raster
from .project import Cut, Project
MAX_WIDTH = 1920
ALPHA_LEVELS = 16 # quantising alpha costs nothing visible and ~32% of the bytes
# A row or column carrying less ink than this is a fleck, not content: at least
# this many pixels, and at least this share of the slice's own size.
_SPECK_INK = 8
_SPECK_SHARE = 0.005
@dataclass
class SliceImage:
"""One rendered slice, before scaling."""
page: int
index: int
gray: np.ndarray
staff: float | None
@property
def width(self) -> int:
return self.gray.shape[1]
def apply_levels(gray: np.ndarray, black: int, white: int) -> np.ndarray:
"""Map [black, white] onto the full range with a lookup table.
A global LUT, not an adaptive method: CLAHE and adaptive thresholding are
tuned for text and eat the thin stuff on notation — hairpin tips, slur ends,
ledger lines, tapered beams.
"""
if (black, white) == (0, 255):
return gray
lo, hi = min(black, white), max(black, white)
if hi <= lo:
return gray
ramp = np.clip((np.arange(256) - lo) * 255.0 / (hi - lo), 0, 255)
return cv2.LUT(gray, ramp.astype(np.uint8))
def page_pixels(project: Project, source: Source, index: int) -> np.ndarray:
"""A page straightened and levelled, ready to be cut."""
page = project.pages[index]
gray = deskew(page_raster(source, index), page.skew)
black, white = project.page_levels(index)
return apply_levels(gray, black, white)
def _boundary(cut: Cut | None, width: int, height: int, *, bottom: bool) -> list[tuple[int, int]]:
"""A cut as pixel points spanning the page, or the page edge when absent."""
if cut is None:
y = height if bottom else 0
return [(0, y), (width, y)]
return [(int(round(x * width)), int(round(y * height))) for x, y in cut.points]
def slice_mask(project: Project, index: int, slot: int, shape: tuple[int, int]) -> np.ndarray:
"""Which pixels of a page belong to one slice.
A slice bounded by a stepped cut is not rectangular, so this is a polygon
rather than a row range: the top boundary left to right, then the bottom
boundary right to left.
"""
height, width = shape
page = project.pages[index]
above, below = page.bounds(slot)
polygon = _boundary(above, width, height, bottom=False)
polygon += _boundary(below, width, height, bottom=True)[::-1]
mask = np.zeros(shape, np.uint8)
cv2.fillPoly(mask, [np.array(polygon, np.int32)], 255)
# The content rectangle is applied here rather than as a separate crop, so
# margin junk can never enter a slice in the first place.
x0, y0, x1, y1 = project.page_content_rect(index)
box = np.zeros(shape, np.uint8)
box[int(y0 * height) : int(y1 * height), int(x0 * width) : int(x1 * width)] = 255
return cv2.bitwise_and(mask, box)
def _ink_bbox(gray: np.ndarray) -> tuple[int, int, int, int] | None:
"""Tight bounds of the ink, ignoring specks.
One scan fleck at the far left would otherwise anchor the trim and shift
that slice relative to every other one.
Measured per row and per column rather than per blob. Judging each blob on
its own area throws away a whole line of lyrics — every letter is its own
small component, and no single one is big enough to keep — which is how a
slice loses its bottom voice's words. A row carrying a line of text carries
plenty of ink *in total*, and a fleck's row carries almost none.
"""
ink = gray < 200
rows, cols = ink.sum(axis=1), ink.sum(axis=0)
kept_rows = np.where(rows >= max(_SPECK_INK, ink.shape[1] * _SPECK_SHARE))[0]
kept_cols = np.where(cols >= max(_SPECK_INK, ink.shape[0] * _SPECK_SHARE))[0]
if not kept_rows.size or not kept_cols.size:
return None
return (
int(kept_cols[0]),
int(kept_rows[0]),
int(kept_cols[-1]) + 1,
int(kept_rows[-1]) + 1,
)
def cut_slice(page: np.ndarray, mask: np.ndarray) -> np.ndarray | None:
"""Extract one slice: everything outside its region becomes paper.
Paper here means white, which the ink→alpha step turns into full
transparency — so a stepped slice's notch composites invisibly on the
viewer's sheet rather than covering the neighbouring system.
"""
isolated = np.where(mask > 0, page, np.uint8(255))
box = _ink_bbox(isolated)
if box is None:
return None
x0, y0, x1, y1 = box
return isolated[y0:y1, x0:x1]
def render_slices(project: Project, source: Source) -> list[SliceImage]:
"""Every kept slice, trimmed but not yet scaled."""
out: list[SliceImage] = []
for index in range(len(project.pages)):
page_state = project.pages[index]
# Only rasterize the page if some slice on it still comes from the scan.
page = None
for slot in range(page_state.slice_count):
if page_state.discards[slot]:
continue
engraved = page_state.replacements[slot]
if engraved and engraved.voices:
# A re-engraved system enters here, at the trim stage, so it
# flows through staff-height normalisation and the rest exactly
# as a scanned one does.
gray = lilypond.render(
lilypond.generate(
engraved, project.key, project.time, page_state.bars[slot]
)
)
else:
if page is None:
page = page_pixels(project, source, index)
gray = cut_slice(page, slice_mask(project, index, slot, page.shape))
if gray is None:
continue # a kept slice that turned out to hold no ink
out.append(SliceImage(index, slot, gray, staff_height(gray, 0, gray.shape[0])))
return out
def scale_song(slices: list[SliceImage], cap: int = MAX_WIDTH) -> list[np.ndarray]:
"""Normalise every slice to one staff height, then fit the song to the cap.
Two steps, both per song. Staff-height normalisation is what makes a
rescanned page — or a re-engraved system — sit at the same note size as its
neighbours; width-based scaling cannot, because width depends on how much
music is in a system rather than on how big it is drawn.
The cap is a ceiling, never a target: a song that comes out narrower stays
narrower, since enlarging a scan past its own resolution buys softness and
bytes and no detail.
"""
if not slices:
return []
measured = [s.staff for s in slices if s.staff]
target = float(np.median(measured)) if measured else 0.0
factors = [target / s.staff if (target and s.staff) else 1.0 for s in slices]
widest = max(s.width * f for s, f in zip(slices, factors))
song = min(1.0, cap / widest) if widest else 1.0
out = []
for s, f in zip(slices, factors):
k = f * song
if abs(k - 1.0) < 1e-3:
out.append(s.gray)
continue
interp = cv2.INTER_AREA if k < 1 else cv2.INTER_CUBIC
out.append(cv2.resize(s.gray, None, fx=k, fy=k, interpolation=interp))
return out
def pad_right(images: list[np.ndarray]) -> list[np.ndarray]:
"""Bring every slice to the song's width, flush left.
A short system simply ends earlier; the padding is paper, so it disappears
when ink becomes alpha.
"""
if not images:
return []
width = max(i.shape[1] for i in images)
return [
i
if i.shape[1] == width
else cv2.copyMakeBorder(i, 0, 0, 0, width - i.shape[1], cv2.BORDER_CONSTANT, value=255)
for i in images
]
def encode(gray: np.ndarray) -> bytes:
"""Ink black, paper transparent, lossless WebP.
Lossless rather than lossy not because lossy looks bad — measured, it
doesn't — but because it is 58% *larger* on line art (ADR 0003).
"""
alpha = 255 - gray
if ALPHA_LEVELS < 256:
# Round to the nearest of ALPHA_LEVELS values spanning 0–255 inclusive.
# Flooring instead would cap full ink at 240 and leave every note
# slightly transparent.
step = 255 / (ALPHA_LEVELS - 1)
alpha = (np.round(alpha / step) * step).astype(np.uint8)
rgba = np.zeros((*gray.shape, 4), np.uint8)
rgba[:, :, 3] = alpha
ok, buf = cv2.imencode(".webp", rgba, [cv2.IMWRITE_WEBP_QUALITY, 101])
if not ok:
raise RuntimeError("WebP encoding failed")
return buf.tobytes()
def render_song(project: Project, source: Source) -> list[bytes]:
"""The whole raster pipeline: project + PDF in, finished slice images out."""
slices = render_slices(project, source)
return [encode(image) for image in pad_right(scale_song(slices))]
pyproject.toml
+13 -1
View File
@@ -4,4 +4,16 @@ version = "0.1.0"
description = "Cuts score PDFs into noteman's slice images and markers" description = "Cuts score PDFs into noteman's slice images and markers"
readme = "README.md" readme = "README.md"
requires-python = ">=3.13" requires-python = ">=3.13"
dependencies = [] dependencies = [
"pymupdf>=1.26",
"numpy>=2.0",
"opencv-python-headless>=4.10",
"pyside6>=6.7",
]
[project.scripts]
noteman-slicer = "noteman_slicer.cli:main"
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
tests/test_detect.py
+108
View File
@@ -0,0 +1,108 @@
"""Runnable check for detection, on a synthetic page.
Draws the structure that matters — a bracket per system, staves, lyrics close
below, and a title and footer far away — so the check is about the algorithm
rather than about any one scan. Run with `python tests/test_detect.py`.
"""
from __future__ import annotations
import sys
from pathlib import Path
import numpy as np
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from noteman_slicer.detect import ( # noqa: E402
deskew,
deskew_angle,
detect_page,
ink_levels,
)
W, H = 1000, 1400
STAFF_GAP = 15 # → staff height 60, so expansion reaches 90px past a bracket
def _system(page: np.ndarray, top: int) -> tuple[int, int]:
"""Two staves joined by a bracket, with a lyric line below. Returns its span."""
bottom = top + 200
page[top:bottom, 100:104] = 0 # the bracket
for staff_top in (top, top + 140):
for i in range(5):
y = staff_top + i * STAFF_GAP
page[y : y + 2, 110:900] = 0
page[staff_top + 90 : staff_top + 105, 200:800] = 0 # lyrics under the staff
return top, bottom
def _page() -> np.ndarray:
page = np.full((H, W), 255, np.uint8)
page[50:70, 300:700] = 0 # title, far above system 1
_system(page, 200)
_system(page, 700)
page[1350:1365, 100:600] = 0 # footer, far below system 2
return page
def main() -> int:
page = _page()
det = detect_page(page)
assert len(det.systems) == 2, f"expected 2 systems, got {len(det.systems)}"
assert len(det.cuts) == 1, det.cuts
first, second = det.systems
# The bracket spans 200–400; the lyric line under the lower staff reaches
# ~445 and must be absorbed.
assert first.top == 200, first.top
assert 400 < first.bottom < 500, first.bottom
assert second.top == 700, second.top
# The title and footer are far from any bracket and must not be swallowed —
# the bug that a chaining expansion reintroduces.
assert first.top > 70, "title block was swallowed"
assert second.bottom < 1350, "footer was swallowed"
# The cut falls between the two systems, in the whitespace.
assert first.bottom < det.cuts[0] < second.top, det.cuts
assert first.staff_height is not None
assert abs(first.staff_height - STAFF_GAP * 4) < STAFF_GAP, first.staff_height
# Skew is recovered to within one fine step.
for angle in (-1.5, 0.8):
found = deskew_angle(deskew(page, angle))
assert abs(found + angle) <= 0.15, f"skew {angle}: got {found}"
# Levels are proposed too. A grey scan left at 0–255 ships its wash to the
# tablet, and the downscale to the song's width only blends it further.
grey = np.full((H, W), 210, np.uint8) # paper, not white
grey[200:400, 100:900] = 70 # ink, not black
black, white = ink_levels(grey)
assert black < 70 < white < 210, (black, white)
# A page already bilevel has nothing between ink and paper to stretch.
assert ink_levels(_page()) == (0, 255)
# A scanner's edge line runs the whole height of the sheet. Being taller
# than every bracket it used to win each overlap and swallow the page into
# one system — Olukainen juomukainen, where five pages of six came out as a
# single slice each.
scanned = _page()
scanned[10 : H - 10, W - 8 : W - 4] = 0
assert len(detect_page(scanned).systems) == 2, "an edge artefact is not a bracket"
# No brackets: every ink run is its own system.
bare = np.full((H, W), 255, np.uint8)
for y in (200, 500, 800):
bare[y : y + 20, 100:900] = 0
assert len(detect_page(bare).systems) == 3
assert detect_page(bare).bracketless
print("ok")
return 0
if __name__ == "__main__":
sys.exit(main())
tests/test_editor.py
+146
View File
@@ -0,0 +1,146 @@
"""Runnable check that the editor builds and its edits reach project state.
Runs offscreen, so it verifies wiring rather than appearance: that the widgets
construct, that an edit changes the model, and that autosave and export work.
"""
from __future__ import annotations
import os
import sys
from pathlib import Path
os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")
import numpy as np # noqa: E402
import pymupdf # noqa: E402
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from PySide6.QtWidgets import QApplication # noqa: E402
from noteman_slicer import bundle # noqa: E402
from noteman_slicer.detect import detect_page # noqa: E402
from noteman_slicer.editor import Editor # noqa: E402
from noteman_slicer.pdf import open_source, page_raster # noqa: E402
from noteman_slicer.project import Cut, Project, default_path # noqa: E402
W, H = 1200, 1600
def _scan_pdf(path: Path) -> None:
art = np.full((H, W), 255, np.uint8)
for top in (300, 800):
art[top : top + 200, 100:104] = 0
for staff in (top, top + 140):
for i in range(5):
art[staff + i * 15 : staff + i * 15 + 2, 110:1100] = 0
pix = pymupdf.Pixmap(pymupdf.csGRAY, W, H, bytearray(art.tobytes()), False)
doc = pymupdf.open()
doc.new_page(width=595, height=842).insert_image(pymupdf.Rect(0, 0, 595, 842), pixmap=pix)
doc.save(path)
def main() -> int:
tmp = Path(__file__).with_name("_tmp")
tmp.mkdir(exist_ok=True)
pdf = tmp / "scan.pdf"
_scan_pdf(pdf)
app = QApplication.instance() or QApplication(sys.argv[:1])
source = open_source(pdf)
gray = page_raster(source, 0)
project = Project.from_detection(pdf, [detect_page(gray)], [gray.shape[0]])
editor = Editor(source, project)
page = project.pages[0]
# Cuts.
before = page.slice_count
editor.view.selected_cut = page.add_cut(Cut.straight(0.5))
editor.view.redraw()
assert page.slice_count == before + 1
# A vertex turns a straight cut into a stepped one.
cut = page.cuts[editor.view.selected_cut]
cut.points.insert(1, (0.4, cut.y_at(0.4)))
cut.points[1] = (0.4, cut.points[1][1] + 0.03)
assert cut.straight_y is None, "the cut should no longer be straight"
editor.view.redraw()
# Discard.
editor.view.selected_slice = 1
was = page.discards[1]
editor.view.toggle_discard()
assert page.discards[1] != was
# Skew and levels reach the model and re-render without raising.
editor.skew.setValue(-1.4)
assert abs(page.skew + 1.4) < 1e-6
# The levels bar carries the page's own histogram and drives the model
# directly — there are no sliders behind it to keep in step.
assert editor.levels.hist.sum() > 0, "the histogram should hold the scan"
editor.levels.set_levels(40, 210)
editor._levels_changed(40, 210)
assert project.page_levels(0) == (40, 210)
editor.rail.picked.emit(0) # the page rail navigates
assert editor.index == 0 and len(editor.rail.buttons) == len(project.pages)
# Metadata.
editor.metadata["title"].setText("Ketun joululaulu")
editor.metadata["composer"].setText("trad.")
assert project.metadata["title"] == "Ketun joululaulu"
# Content rectangle edits, and reset going back to detection's proposal for
# the page as it now stands — not to the whole page, which would undo the
# thing the rectangle exists for.
expected = detect_page(editor._preview(0), skew=0.0).content
page.content_rect = (0.05, 0.02, 0.95, 0.98)
assert project.page_content_rect(0) == (0.05, 0.02, 0.95, 0.98)
editor._reset_rect()
assert project.page_content_rect(0) == expected, (project.page_content_rect(0), expected)
assert project.page_content_rect(0) != (0.0, 0.0, 1.0, 1.0)
# Autosave target, then a round-trip through disk.
editor._save()
saved = default_path(pdf)
assert saved.exists()
reloaded = Project.load(saved)
assert reloaded.metadata["title"] == "Ketun joululaulu"
assert reloaded.pages[0].skew == -1.4
assert reloaded.pages[0].levels == (40, 210)
assert [c.points for c in reloaded.pages[0].cuts] == [c.points for c in page.cuts]
# The page fits the viewport once the window has a real size. show_page's
# own fit runs before layout, when the viewport is still its default.
editor.resize(900, 700)
editor.show()
app.processEvents()
scene = editor.view.sceneRect()
scale = editor.view.transform().m11()
viewport = editor.view.viewport()
fill = max(
scale * scene.width() / viewport.width(),
scale * scene.height() / viewport.height(),
)
# Fit means nearly touching one edge — Qt leaves a small margin of its own.
# A "≤ 1" check alone would pass a page zoomed down to a dot.
assert 0.9 <= fill <= 1.02, f"page is not fitted to the window: {fill:.3f}"
# The bundle is named after the song, not the PDF.
assert bundle.filename(project) == "Ketun-joululaulu.zip"
project.metadata["title"] = "AC/DC: T.N.T. (live)"
assert bundle.filename(project) == "ACDC-T.N.T.-live.zip"
project.metadata["title"] = "Ketun joululaulu"
editor.close()
source.close()
for f in (pdf, saved):
f.unlink()
tmp.rmdir()
print("ok")
return 0
if __name__ == "__main__":
sys.exit(main())
tests/test_lilypond.py
+196
View File
@@ -0,0 +1,196 @@
"""Runnable check for LilyPond slice replacement.
Skips cleanly when LilyPond is not installed — that is the point of the
availability gate, so the check has to honour it.
"""
from __future__ import annotations
import sys
from pathlib import Path
import numpy as np
import pymupdf
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from noteman_slicer import lilypond # noqa: E402
from noteman_slicer.detect import detect_page # noqa: E402
from noteman_slicer.pdf import open_source, page_raster # noqa: E402
from noteman_slicer.detect import staff_count # noqa: E402
from noteman_slicer.project import ( # noqa: E402
Cut,
Project,
Replacement,
Voice,
default_path,
)
from noteman_slicer.render import cut_slice, render_slices, scale_song, slice_mask # noqa: E402
# Notes are relative, so no octave marks except where a leap needs one.
SATB = Replacement(
voices=[
Voice("treble", "c4 d e f | g2 e2", "la la la la la la"),
Voice("bass", "c4 d e f | g2 c2", "la la la la la la"),
]
)
W, H = 1200, 1600
def _scan_pdf(path: Path) -> None:
art = np.full((H, W), 255, np.uint8)
for top in (300, 800):
art[top : top + 200, 100:104] = 0
for staff in (top, top + 140):
for i in range(5):
art[staff + i * 15 : staff + i * 15 + 2, 110:1100] = 0
pix = pymupdf.Pixmap(pymupdf.csGRAY, W, H, bytearray(art.tobytes()), False)
doc = pymupdf.open()
doc.new_page(width=595, height=842).insert_image(pymupdf.Rect(0, 0, 595, 842), pixmap=pix)
doc.save(path)
def main() -> int:
# Bar aliases are string work, so they are checked whether or not LilyPond
# is installed. The old repeat names draw nothing at all in 2.24 — silently,
# which is how a missing repeat reaches a tablet.
aliased = lilypond.generate(
Replacement(voices=[Voice("treble", 'c4 d \\bar ":|" e f \\bar "|:" g', "")]), "c", "4/4"
)
assert '\\bar ":|."' in aliased and '\\bar ".|:"' in aliased, aliased
kept = lilypond.generate(
Replacement(voices=[Voice("treble", 'c4 \\bar "|." d', "")]), "c", "4/4"
)
assert '\\bar "|."' in kept, "a name LilyPond still knows is left alone"
# An octavated clef name must be quoted. Unquoted, `\clef treble_8` is a
# plain treble with a stray "8" markup under the first note, an octave off.
tenor = lilypond.generate(
Replacement(voices=[Voice("treble_8", "c4 d", "")]), "c", "4/4"
)
assert '\\clef "treble_8"' in tenor, tenor
# A bar number is set once, on the first staff, since it is a Score
# property, and is visible only at a line beginning — one number above the
# first bar, as a printed score numbers its systems.
numbered = lilypond.generate(
Replacement(voices=[Voice("treble", "c4 d", ""), Voice("bass", "c4 d", "")]),
"c",
"4/4",
33,
)
assert numbered.count("currentBarNumber = #33") == 1, numbered
assert "break-visibility = #'#(#f #f #t)" in numbered
assert "currentBarNumber" not in lilypond.generate(
Replacement(voices=[Voice("treble", "c4 d", "")]), "c", "4/4"
), "an unnumbered system prints no number"
if not lilypond.available():
print("ok (skipped: LilyPond not installed)")
return 0
tmp = Path(__file__).with_name("_tmp")
tmp.mkdir(exist_ok=True)
pdf = tmp / "scan.pdf"
_scan_pdf(pdf)
# A syntax error must come back readable rather than as a stack trace.
try:
lilypond.render("\\score { this is not lilypond }")
except lilypond.LilypondError as error:
assert str(error), "the error must carry LilyPond's own message"
else:
raise AssertionError("bad source should raise")
# The generator: key at slice level, time used but not printed.
source = lilypond.generate(SATB, "aes", "4/4")
assert source.count("\\new Staff") == 2
assert source.count("\\key aes \\major") == 2, "every staff carries the key"
assert "\\omit Staff.TimeSignature" in source, "a middle system prints no time signature"
assert "\\addlyrics" in source
# Relative entry, referenced to the middle of each clef's staff, so notes
# carry no octave marks.
assert "\\relative c'' { c4 d e f | g2 e2 }" in source
assert "\\relative c { c4 d e f | g2 c2 }" in source
printed = lilypond.generate(
Replacement(voices=SATB.voices, print_time=True), "aes", "4/4"
)
assert "\\omit Staff.TimeSignature" not in printed
override = lilypond.generate(Replacement(voices=SATB.voices, key="d"), "aes", "4/4")
assert "\\key d \\major" in override, "a slice-level key must win over the song's"
# Every key signature and clef the form offers must be real LilyPond.
assert len(lilypond.KEY_SIGNATURES) == 15
assert ("4♭ — A♭ major / F minor", "aes") in lilypond.KEY_SIGNATURES
assert [v for _, v in lilypond.CLEFS] == ["treble", "treble_8", "bass", "alto"]
engraved = lilypond.render(source, dpi=200)
assert engraved.ndim == 2 and engraved.dtype == np.uint8
# -dcrop trims to the ink, so the result is far smaller than a page.
assert engraved.shape[0] < 1200, engraved.shape
assert engraved.min() == 0 and engraved.max() == 255
source = open_source(pdf)
gray = page_raster(source, 0)
project = Project.from_detection(pdf, [detect_page(gray)], [gray.shape[0]])
page = project.pages[0]
assert len(page.replacements) == page.slice_count
kept = project.kept_slices()
(_, first), (_, second) = kept
# Voice count is seeded from the slice: the fixture draws two staves.
preview = cut_slice(gray, slice_mask(project, 0, second, gray.shape))
assert staff_count(preview) == 2, staff_count(preview)
page.replacements[second] = SATB
slices = render_slices(project, source)
assert len(slices) == 2
scanned, replaced = slices
assert scanned.staff and replaced.staff
# The whole point: after normalisation both sit at the same staff height,
# with no manual scaling, even though the sources differ wildly in scale.
factors = [target / s.staff for s, target in ((scanned, 1.0), (replaced, 1.0))]
assert factors # keep the intent readable
out = scale_song(slices)
heights = []
for image, original in zip(out, slices):
k = image.shape[0] / original.gray.shape[0]
heights.append(original.staff * k)
assert abs(heights[0] - heights[1]) < 2.0, f"staff heights should match: {heights}"
# Cut edits keep the replacement aligned with its slice.
index = page.add_cut(Cut.straight(0.97))
assert len(page.replacements) == page.slice_count
assert page.replacements[second] is SATB
page.remove_cut(index)
assert page.replacements[second] is SATB
# Round-trip, including the song-level engraving defaults.
page.bars[second] = 33
project.key, project.time, project.clefs = "aes", "3/4", ["treble", "bass"]
saved = project.save()
reloaded = Project.load(saved)
assert (reloaded.key, reloaded.time, reloaded.clefs) == ("aes", "3/4", ["treble", "bass"])
restored = reloaded.pages[0].replacements[second]
assert restored is not None
assert [v.clef for v in restored.voices] == ["treble", "bass"]
assert restored.voices[0].lyrics == "la la la la la la"
assert reloaded.pages[0].bars[second] == 33, "the slice's bar number survives a save"
assert reloaded.pages[0].replacements[first] is None
source.close()
for f in (pdf, saved, default_path(pdf)):
f.unlink(missing_ok=True)
tmp.rmdir()
print("ok")
return 0
if __name__ == "__main__":
sys.exit(main())
tests/test_markers.py
+227
View File
@@ -0,0 +1,227 @@
"""Runnable check for markers: model, cut edits, and export resolution."""
from __future__ import annotations
import json
import sys
import zipfile
from pathlib import Path
import numpy as np
import pymupdf
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from noteman_slicer import bundle # noqa: E402
from noteman_slicer.bundle import song_json # noqa: E402
from noteman_slicer.detect import detect_page # noqa: E402
from noteman_slicer.pdf import open_source, page_raster # noqa: E402
from noteman_slicer.project import ( # noqa: E402
JUMP_TYPES,
MARKER_TYPES,
Cut,
Marker,
Project,
Replacement,
Voice,
default_path,
)
W, H = 1200, 1600
def _scan_pdf(path: Path) -> None:
art = np.full((H, W), 255, np.uint8)
for top in (300, 800):
art[top : top + 200, 100:104] = 0
for staff in (top, top + 140):
for i in range(5):
art[staff + i * 15 : staff + i * 15 + 2, 110:1100] = 0
pix = pymupdf.Pixmap(pymupdf.csGRAY, W, H, bytearray(art.tobytes()), False)
doc = pymupdf.open()
doc.new_page(width=595, height=842).insert_image(pymupdf.Rect(0, 0, 595, 842), pixmap=pix)
doc.save(path)
def main() -> int:
tmp = Path(__file__).with_name("_tmp")
tmp.mkdir(exist_ok=True)
pdf = tmp / "scan.pdf"
_scan_pdf(pdf)
# noteman's enum, verbatim — this is real coupling between two repos.
assert len(MARKER_TYPES) == 14, MARKER_TYPES
assert len(JUMP_TYPES) == 6
assert "generic_jump" in JUMP_TYPES and "segno" not in JUMP_TYPES
source = open_source(pdf)
gray = page_raster(source, 0)
project = Project.from_detection(pdf, [detect_page(gray)], [gray.shape[0]])
page = project.pages[0]
assert len(page.markers) == page.slice_count
kept = project.kept_slices()
assert len(kept) == 2, kept
(_, first), (_, second) = kept
page.markers[first].append(Marker("rehearsal_letter", label="A"))
page.markers[second].append(Marker("coda"))
page.markers[first].append(Marker("to_coda", destination=(0, second)))
# Cut edits keep markers aligned with their slices.
before = list(page.markers[first])
page.bars[first] = 5
index = page.add_cut(Cut.straight(0.95))
assert len(page.markers) == page.slice_count
assert len(page.bars) == page.slice_count
assert page.markers[first] == before, "markers must not move when a later slice splits"
assert page.bars[first] == 5, "the upper half still starts where the slice did"
page.remove_cut(index)
assert len(page.markers) == page.slice_count
assert len(page.bars) == page.slice_count and page.bars[first] == 5
page.bars[first] = None
# Export resolves (page, slot) to the slice's index in the bundle.
names = [f"{i + 1:03}.webp" for i in range(len(project.kept_slices()))]
project.metadata.update({"title": "Test song", "tempo": "92", "composer": ""})
payload = song_json(project, names)
# Tempo is a number, not a string; empty fields are absent, not "".
assert payload["tempo"] == 92, payload["tempo"]
assert "composer" not in payload
project.metadata["tempo"] = "Andante"
assert "tempo" not in song_json(project, names), "words are not a tempo"
project.metadata["tempo"] = "92"
slices = payload["slices"]
assert [s["file"] for s in slices] == names
assert slices[0]["markers"][0] == {"type": "rehearsal_letter", "label": "A"}
assert slices[1]["markers"][0] == {"type": "coda"}
assert slices[0]["markers"][1] == {"type": "to_coda", "destination": 1}
# A re-engraved slice carries its notation into the bundle; a scanned one
# carries none. This is what makes a later edit or a MIDI render possible
# from the bundle alone.
project.key, project.time = "aes", "3/4"
page.replacements[second] = Replacement(
voices=[Voice("treble", "c4 d e f", "la la la la"), Voice("bass", " c4 d e f ", " ")],
)
page.bars[second] = 33
engraved = song_json(project, names)["slices"]
assert "engraving" not in engraved[0], "a scanned slice has no notation"
ly = engraved[1]["engraving"]
assert ly["lang"] == "lilypond"
# Song defaults are resolved per slice: reading one slice needs no context.
assert (ly["key"], ly["time"], ly["print_time"]) == ("aes", "3/4", False)
# The bar number is on the slice, not the engraving: a scanned system is
# numbered in the score just the same.
assert engraved[1]["bar"] == 33 and "bar" not in ly, engraved[1]
assert ly["voices"][0] == {"clef": "treble", "notes": "c4 d e f", "lyrics": "la la la la"}
assert "lyrics" not in ly["voices"][1], "an empty field is absent, not empty"
assert ly["voices"][1]["notes"] == "c4 d e f"
override = Replacement(voices=page.replacements[second].voices, key="d", print_time=True)
page.replacements[second] = override
ly = song_json(project, names)["slices"][1]["engraving"]
assert (ly["key"], ly["time"], ly["print_time"]) == ("d", "3/4", True)
page.replacements[second] = None
# A jump whose target got discarded is dropped, not exported dangling.
project.pages[0].discards[second] = True
dropped = song_json(project, ["001.webp"])
assert all(m["type"] != "to_coda" for m in dropped["slices"][0].get("markers", []))
project.pages[0].discards[second] = False
# Round-trip through the project file.
saved = project.save()
reloaded = Project.load(saved)
assert reloaded.pages[0].markers[first][0].label == "A"
assert reloaded.pages[0].markers[first][1].destination == (0, second)
assert reloaded.pages[0].markers[second][0].type == "coda"
# And through a real bundle.
reloaded.metadata["title"] = "Test song"
out = bundle.write(reloaded, source, tmp / "song.zip")
with zipfile.ZipFile(out) as zf:
meta = json.loads(zf.read("song.json"))
assert meta["slices"][0]["markers"][1]["destination"] == 1, meta["slices"]
# And back out again. The bundle carries the cuts, so reopening it rebuilds
# the project rather than re-cutting the score — and a jump goes back from
# an array index to the (page, slot) the editor works in.
reloaded.pages[0].replacements[second] = Replacement(
voices=[Voice("treble", "c4 d", "la la")]
)
reloaded.pages[0].bars[second] = 7
out = bundle.write(reloaded, source, tmp / "song.zip")
opened, unpacked = bundle.read(out, tmp / "reopened.pdf")
assert unpacked.exists() and unpacked.stat().st_size > 0
assert opened.metadata["title"] == "Test song"
assert len(opened.pages) == len(reloaded.pages)
back = opened.pages[0]
assert back.discards == reloaded.pages[0].discards
assert [len(c.points) for c in back.cuts] == [len(c.points) for c in reloaded.pages[0].cuts]
assert back.markers[first][1].destination == (0, second), back.markers[first][1].destination
assert back.markers[second][0].type == "coda"
assert back.bars[second] == 7
assert back.replacements[second].voices[0].lyrics == "la la"
# A bundle from a producer that records no cuts: refused by default, and
# cut from scratch by detection when the caller says so. The slices are in
# reading order either way, so markers can be lined up by position — but
# only when detection finds exactly as many.
plain = tmp / "plain.zip"
with zipfile.ZipFile(out) as src, zipfile.ZipFile(plain, "w") as dst:
for name in src.namelist():
data = src.read(name)
if name == "song.json":
manifest = json.loads(data)
manifest.pop("source")
for entry in manifest["slices"]:
entry.pop("page", None)
entry.pop("slot", None)
data = json.dumps(manifest).encode()
dst.writestr(name, data)
assert bundle.has_cuts(out) and not bundle.has_cuts(plain)
try:
bundle.read(plain, tmp / "nocuts.pdf")
except bundle.NoCuts as error:
assert "no cuts" in str(error), error
else:
raise AssertionError("a bundle without cuts should not open silently")
cut_again, again_pdf = bundle.read(plain, tmp / "nocuts.pdf", detect=True)
assert again_pdf.exists()
assert cut_again.metadata["title"] == "Test song", "the title block still comes back"
assert len(cut_again.kept_slices()) == len(reloaded.kept_slices())
placed = [m for page in cut_again.pages for slot in page.markers for m in slot]
assert len(placed) == 3, placed
assert placed[0].label == "A"
# Unpacking never lands on files that are already there.
try:
bundle.read(out, tmp / "reopened.pdf")
except ValueError as error:
assert "already exists" in str(error), error
else:
raise AssertionError("reopening over an existing PDF should be refused")
source.close()
for f in (
pdf,
out,
plain,
saved,
unpacked,
again_pdf,
default_path(unpacked),
default_path(again_pdf),
default_path(pdf),
):
f.unlink(missing_ok=True)
tmp.rmdir()
print("ok")
return 0
if __name__ == "__main__":
sys.exit(main())
tests/test_pdf.py
+104
View File
@@ -0,0 +1,104 @@
"""Runnable check for source classification and raster loading.
Builds its own PDFs so it needs no corpus files (scores are copyrighted and
gitignored). Run with `python tests/test_pdf.py`.
"""
from __future__ import annotations
import sys
from pathlib import Path
import numpy as np
import pymupdf
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from noteman_slicer.pdf import SourceType, open_source, page_raster # noqa: E402
A4 = pymupdf.paper_rect("a4")
def _vector_pdf(path: Path, pages: int = 2) -> None:
doc = pymupdf.open()
for _ in range(pages):
page = doc.new_page(width=A4.width, height=A4.height)
page.draw_line((50, 100), (A4.width - 50, 100))
page.insert_text((50, 150), "notation", fontsize=24)
doc.save(path)
def _scan_pdf(path: Path, pages: int = 2, w: int = 1653, h: int = 2332, rotation: int = 0) -> None:
"""Each page is one full-page grayscale image — what a real scan looks like.
`rotation` reproduces a sheet fed sideways: the image is stored in its own
orientation and /Rotate turns it upright for a viewer.
"""
art = np.full((h, w), 255, np.uint8)
art[500:505, 100 : w - 100] = 0 # a staff line, so it isn't uniform
art[:60, :60] = 0 # a corner mark, so orientation is checkable
pix = pymupdf.Pixmap(pymupdf.csGRAY, w, h, bytearray(art.tobytes()), False)
doc = pymupdf.open()
for _ in range(pages):
page = doc.new_page(width=A4.width, height=A4.width * h / w)
page.insert_image(page.rect, pixmap=pix)
page.set_rotation(rotation)
doc.save(path)
def main() -> int:
tmp = Path(__file__).with_name("_tmp")
tmp.mkdir(exist_ok=True)
vec, scan = tmp / "vector.pdf", tmp / "scan.pdf"
_vector_pdf(vec)
_scan_pdf(scan)
src = open_source(vec)
assert src.type is SourceType.VECTOR, src.type
assert not src.overridden
page = page_raster(src, 0)
# Rendered at 600 DPI, so an A4 page is ~4960px wide.
assert page.ndim == 2 and page.dtype == np.uint8, (page.ndim, page.dtype)
assert 4900 < page.shape[1] < 5000, page.shape
src.close()
src = open_source(scan)
assert src.type is SourceType.RASTER, src.type
page = page_raster(src, 0)
# Native resolution of the embedded image, NOT a 600 DPI re-render.
assert page.shape == (2332, 1653), page.shape
assert page.min() == 0 and page.max() == 255, (page.min(), page.max())
src.close()
# The corner mark sits top-left in an upright scan.
assert page[:60, :60].max() == 0 and page[:60, -60:].min() == 255
# A sideways scan comes back upright: the page's /Rotate applies to the
# image extracted by xref, which bypasses it. Okular gets this right and
# the slicer used to not.
sideways = tmp / "sideways.pdf"
_scan_pdf(sideways, pages=1, w=2332, h=1653, rotation=90)
src = open_source(sideways)
assert src.type is SourceType.RASTER
turned = page_raster(src, 0)
assert turned.shape == (2332, 1653), turned.shape
# Turned clockwise, so the mark that was top-left is now top-right.
assert turned[:60, -60:].max() == 0 and turned[:60, :60].min() == 255
src.close()
# An override must win over detection, and say so.
src = open_source(scan, SourceType.VECTOR)
assert src.type is SourceType.VECTOR and src.detected is SourceType.RASTER
assert src.overridden
assert page_raster(src, 0).shape[1] > 4000, "override must force a render"
src.close()
for f in (vec, scan, sideways):
f.unlink()
tmp.rmdir()
print("ok")
return 0
if __name__ == "__main__":
sys.exit(main())
tests/test_pdfopt.py
+96
View File
@@ -0,0 +1,96 @@
"""Runnable check for optional PDF shrinking, including what it refuses to do."""
from __future__ import annotations
import sys
from pathlib import Path
import numpy as np
import pymupdf
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from noteman_slicer.pdfopt import MIN_DPI, optimise # noqa: E402
A4_PT = (595, 842)
def _pdf(path: Path, width: int, height: int, *, colour: bool = False, bilevel: bool = False):
"""One full-page image of ruled lines, at the given pixel size."""
art = np.full((height, width, 3), 255, np.uint8)
for i in range(6):
y = int(height * (0.2 + i * 0.03))
art[y : y + max(1, height // 900), int(width * 0.1) : int(width * 0.9)] = 0
if colour:
art[: height // 3, :, 0] = 40 # a strong blue cast over the top third
art[: height // 3, :, 1] = 90
grey = art[:, :, 0] if not colour else None
doc = pymupdf.open()
page = doc.new_page(width=A4_PT[0], height=A4_PT[1])
if bilevel:
pix = pymupdf.Pixmap(pymupdf.csGRAY, width, height, bytearray(grey.tobytes()), False)
page.insert_image(page.rect, pixmap=pix)
doc.save(path, garbage=4, deflate=True)
# Re-save through a 1-bit PNG so the stored image really is bilevel.
import cv2
ok, buf = cv2.imencode(".png", (grey > 127).astype(np.uint8) * 255)
doc2 = pymupdf.open()
p2 = doc2.new_page(width=A4_PT[0], height=A4_PT[1])
p2.insert_image(p2.rect, stream=buf.tobytes())
doc2.save(path, garbage=4, deflate=True)
return
stream = art if colour else np.dstack([grey] * 3)
import cv2
ok, buf = cv2.imencode(".jpg", stream, [cv2.IMWRITE_JPEG_QUALITY, 92])
page.insert_image(page.rect, stream=buf.tobytes())
doc.save(path, garbage=4, deflate=True)
def main() -> int:
tmp = Path(__file__).with_name("_tmp")
tmp.mkdir(exist_ok=True)
# A4 is 8.26in wide, so 2480px is ~300 DPI and 800px is ~97 DPI.
fine, coarse, colour = tmp / "fine.pdf", tmp / "coarse.pdf", tmp / "colour.pdf"
_pdf(fine, 2480, 3508)
_pdf(coarse, 800, 1130)
_pdf(colour, 2480, 3508, colour=True)
data, report = optimise(pymupdf.open(fine), fine.stat().st_size)
assert report.converted == 1, report.summary()
assert data, "a greyscale scan at 300 DPI should shrink"
assert report.ratio < 0.9, report.ratio
# The result must still be a readable PDF of the same page count.
assert len(pymupdf.open(stream=data, filetype="pdf")) == 1
# Too coarse: staff lines would break, so it is left alone.
_, report = optimise(pymupdf.open(coarse), coarse.stat().st_size)
assert report.converted == 0, report.summary()
assert any("DPI" in reason for reason in report.skipped), report.skipped
# Genuine colour: artwork is not thrown away.
_, report = optimise(pymupdf.open(colour), colour.stat().st_size)
assert report.converted == 0, report.summary()
assert any("colour" in reason for reason in report.skipped), report.skipped
# A no-op run reports honestly rather than returning something bigger.
empty = pymupdf.open()
empty.new_page()
data, report = optimise(empty, 1)
assert data == b"" and report.converted == 0
assert report.ratio == 1.0
assert MIN_DPI >= 150, "the floor exists to protect thin staff lines"
for f in (fine, coarse, colour):
f.unlink(missing_ok=True)
tmp.rmdir()
print("ok")
return 0
if __name__ == "__main__":
sys.exit(main())
tests/test_project.py
+88
View File
@@ -0,0 +1,88 @@
"""Runnable check for project state: round-trip, cut edits, discard pre-set."""
from __future__ import annotations
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from noteman_slicer.detect import PageDetection, System # noqa: E402
from noteman_slicer.project import Cut, Project, default_path # noqa: E402
def main() -> int:
tmp = Path(__file__).with_name("_tmp")
tmp.mkdir(exist_ok=True)
pdf = tmp / "song.pdf"
pdf.write_bytes(b"%PDF-1.7 not really a pdf, only its bytes are hashed")
height = 1000
detection = PageDetection(
skew=-1.1,
systems=[System(200, 400, 60.0), System(600, 800, 60.0)],
cuts=[500],
)
project = Project.from_detection(pdf, [detection], [height])
page = project.pages[0]
# One cut between the systems, plus a boundary cut above the first and
# below the last — so the header and footer become their own slices.
assert len(page.cuts) == 3, [c.points for c in page.cuts]
assert page.discards == [True, False, False, True], page.discards
assert page.slice_count == 4
assert project.kept_slices() == [(0, 1), (0, 2)], project.kept_slices()
# Geometry is normalised, so it survives any change of resolution.
assert all(0.0 <= y <= 1.0 for cut in page.cuts for _, y in cut.points)
assert page.cuts[1].straight_y == 0.5
# A straight cut is flat; a stepped one is not, and interpolates.
step = Cut([(0.0, 0.20), (0.35, 0.20), (0.35, 0.40), (1.0, 0.40)])
assert step.straight_y is None
assert step.y_at(0.0) == 0.20
assert step.y_at(1.0) == 0.40
assert step.y_at(0.35) == 0.20 or step.y_at(0.35) == 0.40
assert step.highest == 0.20 and step.lowest == 0.40
# Adding a cut splits a slice and keeps that slice's flag on both halves.
before = page.slice_count
index = page.add_cut(Cut.straight(0.65))
assert page.slice_count == before + 1
assert index == 2, index
assert page.discards == [True, False, False, False, True], page.discards
# Removing it merges them again.
page.remove_cut(index)
assert page.slice_count == before
assert page.discards == [True, False, False, True], page.discards
# Round-trip.
saved = project.save()
assert saved == default_path(pdf), saved
reloaded = Project.load(saved)
assert reloaded.pages[0].skew == -1.1
assert reloaded.pages[0].discards == page.discards
assert [c.points for c in reloaded.pages[0].cuts] == [c.points for c in page.cuts]
assert reloaded.source_hash == project.source_hash
assert not reloaded.source_changed()
# A project is spent once exported: reopening starts fresh.
assert not reloaded.exported
reloaded.exported = True
reloaded.save()
assert Project.load(saved).exported
# A PDF edited underneath must be reported, not silently re-cut.
pdf.write_bytes(b"%PDF-1.7 different bytes entirely")
assert reloaded.source_changed()
for f in (pdf, saved):
f.unlink()
tmp.rmdir()
print("ok")
return 0
if __name__ == "__main__":
sys.exit(main())
tests/test_render.py
+185
View File
@@ -0,0 +1,185 @@
"""Runnable check for the render pipeline and bundle export."""
from __future__ import annotations
import json
import sys
import zipfile
from pathlib import Path
import cv2
import numpy as np
import pymupdf
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from noteman_slicer import bundle # noqa: E402
from noteman_slicer.detect import detect_page # noqa: E402
from noteman_slicer.pdf import open_source, page_raster # noqa: E402
from noteman_slicer.project import Cut, Project, default_path # noqa: E402
from noteman_slicer.render import ( # noqa: E402
ALPHA_LEVELS,
_ink_bbox,
apply_levels,
encode,
pad_right,
render_slices,
scale_song,
)
W, H = 1200, 1600
GAP = 15
def _system(page: np.ndarray, top: int, right: int) -> None:
"""A bracket plus two staves, with a lyric line under each."""
page[top : top + 200, 100:104] = 0
for staff in (top, top + 140):
for i in range(5):
page[staff + i * GAP : staff + i * GAP + 2, 110:right] = 0
page[staff + 90 : staff + 105, 200 : right - 100] = 0
def _scan_pdf(path: Path) -> None:
art = np.full((H, W), 255, np.uint8)
art[40:60, 400:800] = 0 # title, far from any system
_system(art, 300, 1100)
_system(art, 800, 900) # narrower: exercises the right pad
pix = pymupdf.Pixmap(pymupdf.csGRAY, W, H, bytearray(art.tobytes()), False)
doc = pymupdf.open()
page = doc.new_page(width=595, height=842)
page.insert_image(page.rect, pixmap=pix)
doc.save(path)
def main() -> int:
tmp = Path(__file__).with_name("_tmp")
tmp.mkdir(exist_ok=True)
pdf = tmp / "scan.pdf"
_scan_pdf(pdf)
source = open_source(pdf)
gray = page_raster(source, 0)
project = Project.from_detection(pdf, [detect_page(gray)], [gray.shape[0]])
slices = render_slices(project, source)
assert len(slices) == 2, f"expected 2 kept slices, got {len(slices)}"
# The title is far from any bracket, so it is not in a kept slice: both
# slices must be shorter than the gap between the systems.
assert all(s.gray.shape[0] < 400 for s in slices), [s.gray.shape for s in slices]
# System 2 is drawn narrower, so before padding the widths differ.
assert slices[0].width != slices[1].width, "the fixture should differ in width"
scaled = scale_song(slices, cap=4000) # a cap far above the fixture
assert all(abs(a.shape[1] - b.width) <= 2 for a, b in zip(scaled, slices)), (
"never upscale: a song narrower than the cap must be left alone"
)
padded = pad_right(scale_song(slices))
assert len({p.shape[1] for p in padded}) == 1, "slices must share one width"
assert max(p.shape[1] for p in padded) <= 1920
rgba = cv2.imdecode(np.frombuffer(encode(padded[0]), np.uint8), cv2.IMREAD_UNCHANGED)
assert rgba.shape[2] == 4
assert rgba[:, :, :3].max() == 0, "ink must be pure black"
assert rgba[:, :, 3].max() == 255, "full ink must be fully opaque"
assert rgba[:, :, 3].min() == 0, "paper must be fully transparent"
assert len(np.unique(rgba[:, :, 3])) <= ALPHA_LEVELS
# Trim keeps a line of lyrics and drops a fleck. Each letter is its own
# small blob, so judging blobs by area threw the whole line away and the
# bottom voice lost its words; a fleck's row carries almost no ink at all.
art = np.full((300, 800), 255, np.uint8)
art[100:150, 50:750] = 0 # a staff
for x in range(60, 700, 30): # lyrics: many small glyphs, one row
art[200:220, x : x + 14] = 0
art[5:9, 10:14] = 0 # a fleck in the far corner
x0, y0, x1, y1 = _ink_bbox(art)
assert (y0, y1) == (100, 220), f"lyrics kept, fleck dropped: {(y0, y1)}"
assert (x0, x1) == (50, 750), (x0, x1)
assert _ink_bbox(np.full((50, 50), 255, np.uint8)) is None, "blank slice has no box"
# Levels: a white point below the paper value wipes the paper out entirely.
faint = np.full((10, 10), 200, np.uint8)
assert apply_levels(faint, 0, 180).max() == 255
# The Engel case: a section label printed in the left margin at a height
# that belongs to the *next* system. A straight cut cannot separate it from
# the previous system's lyrics; a stepped one can.
label_top, label_bottom = 620, 680
labelled = tmp / "labelled.pdf"
art = np.full((H, W), 255, np.uint8)
_system(art, 300, 1100)
_system(art, 800, 900)
art[label_top:label_bottom, 120:300] = 0 # the label
art[label_top:label_bottom, 500:1000] = 0 # system 1's trailing lyrics, same rows
pix = pymupdf.Pixmap(pymupdf.csGRAY, W, H, bytearray(art.tobytes()), False)
doc = pymupdf.open()
doc.new_page(width=595, height=842).insert_image(pymupdf.Rect(0, 0, 595, 842), pixmap=pix)
doc.save(labelled)
src2 = open_source(labelled)
g2 = page_raster(src2, 0)
proj2 = Project.from_detection(labelled, [detect_page(g2)], [g2.shape[0]])
page = proj2.pages[0]
scale = g2.shape[0] / H
def ink(images: list) -> list[int]:
"""Ink in the left margin of each slice — where the label sits."""
return [int((i.gray[:, : int(i.width * 0.3)] < 128).sum()) for i in images]
# Straight cut through the middle of that band: the label goes with
# whichever side the line falls on, and cannot be separated.
band_mid = (label_top + label_bottom) / 2 * scale / g2.shape[0]
page.cuts[1] = Cut.straight(band_mid)
straight_ink = ink(render_slices(proj2, src2))
# Stepped: above the label on the left, below the lyrics on the right.
above = (label_top - 10) * scale / g2.shape[0]
below = (label_bottom + 10) * scale / g2.shape[0]
page.cuts[1] = Cut([(0.0, above), (0.35, above), (0.35, below), (1.0, below)])
stepped_ink = ink(render_slices(proj2, src2))
# The straight cut splits the label down the middle; the stepped cut gives
# all of it to the lower slice and none to the upper.
assert stepped_ink[1] > straight_ink[1], (
f"the label must move into the lower slice: {straight_ink} → {stepped_ink}"
)
assert stepped_ink[0] < straight_ink[0], (
f"and out of the upper one: {straight_ink} → {stepped_ink}"
)
src2.close()
labelled.unlink()
# Bundle. A title is required; everything else is optional.
try:
bundle.write(project, source, tmp / "untitled.zip")
except ValueError as error:
assert "title" in str(error)
else:
raise AssertionError("export without a title should be refused")
project.metadata["title"] = "Test song"
out = bundle.write(project, source, tmp / "song.zip")
with zipfile.ZipFile(out) as zf:
names = zf.namelist()
assert "song.json" in names and "original.pdf" in names, names
meta = json.loads(zf.read("song.json"))
assert meta["v"] == 1
files = [s["file"] for s in meta["slices"]]
assert files == ["001.webp", "002.webp"], files
assert all(f in names for f in files)
source.close()
# Exporting marks the project spent, which writes the project file.
for f in (pdf, out, default_path(pdf)):
f.unlink(missing_ok=True)
tmp.rmdir()
print("ok")
return 0
if __name__ == "__main__":
sys.exit(main())
uv.lock
Generated
+158
View File
@@ -0,0 +1,158 @@
version = 1
revision = 3
requires-python = ">=3.13"
[[package]]
name = "noteman-slicer"
version = "0.1.0"
source = { editable = "." }
dependencies = [
{ name = "numpy" },
{ name = "opencv-python-headless" },
{ name = "pymupdf" },
{ name = "pyside6" },
]
[package.metadata]
requires-dist = [
{ name = "numpy", specifier = ">=2.0" },
{ name = "opencv-python-headless", specifier = ">=4.10" },
{ name = "pymupdf", specifier = ">=1.26" },
{ name = "pyside6", specifier = ">=6.7" },
]
[[package]]
name = "numpy"
version = "2.5.1"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "https://files.pythonhosted.org/packages/22/fd/89965aa4ac08c74998539fcbf24fa3540f3e15237fbeb6bcf9c908f4aade/numpy-2.5.1.tar.gz", hash = "sha256:a48a113e6afea91f5608793bafa7ef2ad481fefbda87ec5069f483de61cb9fa3", size = 20755553, upload-time = "2026-07-04T17:08:00.933Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/eb/07/ec2a3f0c91761581d4b7104a740791800025983f9a4dc4e73f91a99aeac4/numpy-2.5.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:0bfebd8695f9863592fe744be833a258120b14a9f39da255e8aa8fade2c0ddd1", size = 16796419, upload-time = "2026-07-04T17:06:40.37Z" },
{ url = "https://files.pythonhosted.org/packages/ab/ab/ddb499fc4f8780354395face5b65c7fd107bcd6e1d667a5f07d046956f6f/numpy-2.5.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:30b44a6b53a7ae63c54c089a8726e5563ed302716c5b7ccc85afade40b0e7ff6", size = 11765832, upload-time = "2026-07-04T17:06:42.768Z" },
{ url = "https://files.pythonhosted.org/packages/88/b3/3c28c558a09fc72100c646dac6d2fce8e834c471b0edca01a29996706117/numpy-2.5.1-cp313-cp313-macosx_14_0_arm64.whl", hash = "sha256:6165343f81b56ef8f514f396989e529b61d9dc709b99421b07e9f3e698e2287d", size = 5325143, upload-time = "2026-07-04T17:06:45.466Z" },
{ url = "https://files.pythonhosted.org/packages/5e/0e/ce19b985bb15c596f4f05954e76cccc77c845083b3b8f938a6c68e523128/numpy-2.5.1-cp313-cp313-macosx_14_0_x86_64.whl", hash = "sha256:4939237038ada79308dda3204ac6462df056b5672b2e25db1149cf873668b3e1", size = 6659749, upload-time = "2026-07-04T17:06:47.288Z" },
{ url = "https://files.pythonhosted.org/packages/2e/20/1ee6614d64332a1bba6411f38e68cb79eec1b2459e20a623777c5c5492a2/numpy-2.5.1-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1c6759f538fb912fc46de0a6b1758ccf7b57bc7c7ebebc23974fdac3de8db0cd", size = 15164716, upload-time = "2026-07-04T17:06:49.494Z" },
{ url = "https://files.pythonhosted.org/packages/ed/a7/2bcd3fdbb87804755c35b729bf8709d62025c5f4cfd7d5b2415997097515/numpy-2.5.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9726558e8db4a5bf7929a70ae50f63abda4daf0efe810e3bfbab95976f75fc1a", size = 16661440, upload-time = "2026-07-04T17:06:52.061Z" },
{ url = "https://files.pythonhosted.org/packages/fc/d7/a41e3310c886fe457d36e670bbf24fae411aca8a7b6ad92a32afd924077c/numpy-2.5.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:3935f3b419b244a02732676fa5317a9193cc596a4c0646db07e5b421229ac9f7", size = 16526305, upload-time = "2026-07-04T17:06:54.605Z" },
{ url = "https://files.pythonhosted.org/packages/53/75/4333a9a707c1edd3a4e1a0c58eca52c0f31e55089fa80db02b5565b24df7/numpy-2.5.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:dc932a65ded7ce9013d120845a2514dcccb1a67bfc8deb8d37633762951904a6", size = 18423008, upload-time = "2026-07-04T17:06:57.54Z" },
{ url = "https://files.pythonhosted.org/packages/ee/90/e314a32b1c11a2ffe818ddad3a57b50b4b6e1b6c487192eb50cdef0415d0/numpy-2.5.1-cp313-cp313-win32.whl", hash = "sha256:4b4ff1608417eb7a59da7b967bbb798cacfe071d2caf526a24281cd562072ed9", size = 6063885, upload-time = "2026-07-04T17:07:00.14Z" },
{ url = "https://files.pythonhosted.org/packages/10/70/800b3fca480af32df9e8ea9f3d4a0c8feb4b32d7f195d174eabbda4829ad/numpy-2.5.1-cp313-cp313-win_amd64.whl", hash = "sha256:6c3fe51bc6a16453d452997053454f309e8e0ed7b42d6b361ce4ac8c32913d74", size = 12425674, upload-time = "2026-07-04T17:07:02.387Z" },
{ url = "https://files.pythonhosted.org/packages/8b/0b/196350c122f50f6ca56846f2d71efd5e0d24b7b2e07355e019b2e2c7a11e/numpy-2.5.1-cp313-cp313-win_arm64.whl", hash = "sha256:f7feb014281029e628ba2d5a007407443b06e418b6fe451d1e2adcbc8eba0107", size = 10350256, upload-time = "2026-07-04T17:07:04.878Z" },
{ url = "https://files.pythonhosted.org/packages/db/f4/731b6085a83faf6ca843394cbd5e217280c214399f7e8b21b9f552af0ae2/numpy-2.5.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:7c786fe9a5bbe360022e584c5a34cf6b54265c71bd7ec8ac3d8fec38968071f8", size = 16795063, upload-time = "2026-07-04T17:07:07.374Z" },
{ url = "https://files.pythonhosted.org/packages/bf/64/0e215f2048dd11a55bb989ed41b3585ef57452404e638d703a211a3e4157/numpy-2.5.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:32985c896d897419ef8da6917872d80b78ad0ea26d85b23245c7366ffde76d75", size = 11776652, upload-time = "2026-07-04T17:07:09.907Z" },
{ url = "https://files.pythonhosted.org/packages/b5/59/2b844c7a6e9deff69b404a66221e1542937734f65d5e6e39411876053862/numpy-2.5.1-cp314-cp314-macosx_14_0_arm64.whl", hash = "sha256:efd736408cc97c79b9e6917338dfc8f06013b2274f992e96b1d9a81a71e2a2c2", size = 5335944, upload-time = "2026-07-04T17:07:12.227Z" },
{ url = "https://files.pythonhosted.org/packages/86/51/9bf7cb2cabcebc9e017e4ec7e6322b378317a542c08b4cb68479c1efc716/numpy-2.5.1-cp314-cp314-macosx_14_0_x86_64.whl", hash = "sha256:ab84dc6b074fa881cae55bea94cc4f68e285181ba7f32497bf7dee6b1496165b", size = 6656266, upload-time = "2026-07-04T17:07:14.368Z" },
{ url = "https://files.pythonhosted.org/packages/83/3e/fb7615b211b82a32f44d5180a6d421b61f84d4fadd578b48ba4ac34e189f/numpy-2.5.1-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:caf3e317d33d60c37986b452613f4ab51246d0691350c03d0cb4a898627f4a95", size = 15179720, upload-time = "2026-07-04T17:07:16.272Z" },
{ url = "https://files.pythonhosted.org/packages/41/5f/0f992cb24560673496c5d68de61913b57166ce530ffda07c1f280e0cc464/numpy-2.5.1-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:54ad769f17bc2d833b620851989f62054fb9ab93c969d9e1dc3c8e3d56beea21", size = 16664835, upload-time = "2026-07-04T17:07:19.021Z" },
{ url = "https://files.pythonhosted.org/packages/a2/2f/97d6475ee91afe2587797d09446f9d3e475ad4cb681662d824809327b75a/numpy-2.5.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:c12afb53450fa976d4c681c50a7423729a4c51c0465ed9f32b8a9cabbc472373", size = 16539135, upload-time = "2026-07-04T17:07:22.015Z" },
{ url = "https://files.pythonhosted.org/packages/c4/5b/4db81e4ba0be7e2776b1de68c82aa862c7f8ec27e1b4927d4ae075e20678/numpy-2.5.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:e8c11c405efc5ff6816d5983c96cdfa215bab3428961243af3ff59b228490438", size = 18426684, upload-time = "2026-07-04T17:07:24.941Z" },
{ url = "https://files.pythonhosted.org/packages/1f/64/c0ba2d90724d450279a7df8f32057241070250a26a7e2b5337d77347f481/numpy-2.5.1-cp314-cp314-win32.whl", hash = "sha256:f2479a47f8d5932d1718168a681ad6e536a9df484c83cfcf9de365e164537ace", size = 6116103, upload-time = "2026-07-04T17:07:27.622Z" },
{ url = "https://files.pythonhosted.org/packages/c1/1a/837f9ed7405adcd7a40538792eb169eddd8fa5630c16a1ef49dae71a30f4/numpy-2.5.1-cp314-cp314-win_amd64.whl", hash = "sha256:24d0eb82c0541d3415a33425db64ae439dffccd7b4dbcb30e7c35120205c506a", size = 12562177, upload-time = "2026-07-04T17:07:29.887Z" },
{ url = "https://files.pythonhosted.org/packages/22/ed/49707938b6dd0a78a9178dd93227dc89e4c11af47f5c798d70366e8d0483/numpy-2.5.1-cp314-cp314-win_arm64.whl", hash = "sha256:5a4c988b38d261deeeaad9954e3deb091ad905c94e8bb6708654ef1d97f286b0", size = 10627739, upload-time = "2026-07-04T17:07:32.568Z" },
{ url = "https://files.pythonhosted.org/packages/a6/c7/bb4b882cfe7f299cbc8b66e42e7dd78cf9d14e40f9469fc5e3db7e15b3bd/numpy-2.5.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:a33276be12fa045805f477f22482088b66bb758ffbe89a9d21457de863a32e22", size = 11894709, upload-time = "2026-07-04T17:07:34.941Z" },
{ url = "https://files.pythonhosted.org/packages/40/3f/5af7f4a7f6224aef48017aa82bb6174c7a659d724be0c75017b7e64a55b4/numpy-2.5.1-cp314-cp314t-macosx_14_0_arm64.whl", hash = "sha256:f089d7b00756190aacf1f5d34bdf38c3c430ac82b4f868f8cede73380460fce7", size = 5453810, upload-time = "2026-07-04T17:07:37.495Z" },
{ url = "https://files.pythonhosted.org/packages/20/c9/3474309bc94d634d3f9c3eddf03250ecb8c22cd948ef16fef69a77cc5d7b/numpy-2.5.1-cp314-cp314t-macosx_14_0_x86_64.whl", hash = "sha256:09e9bfd8d2cf479c7d174804fb3811c53a8e9f20a37444008606b57d6b7a826d", size = 6761189, upload-time = "2026-07-04T17:07:39.563Z" },
{ url = "https://files.pythonhosted.org/packages/90/8a/558ae39fdd55d7e7f7fef9a84a6e964ac6b23edbd2a07e52bb084500507d/numpy-2.5.1-cp314-cp314t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e68d8dd1e7eba712948f2053a29ec86917bc70ba1358df869d9f06649ef9cf09", size = 15225039, upload-time = "2026-07-04T17:07:41.682Z" },
{ url = "https://files.pythonhosted.org/packages/63/27/ca7392b2d030277bdf0273e7d23255b3ee57d57a7c170a6f4fb3981e1e5d/numpy-2.5.1-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:99d5095fa265a0c4152e7bb12759e14381ef5496152f1ce58f44bdf55c44beb4", size = 16701306, upload-time = "2026-07-04T17:07:44.611Z" },
{ url = "https://files.pythonhosted.org/packages/02/42/03d53ae7996c44d4374a8262e9dc41671fd56cbb98f7d47ef85cf5da4c6b/numpy-2.5.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:ab87a91b3cc3382b8956095bd8f95e00cf679bb81554339be1a2ba404a1473c1", size = 16589955, upload-time = "2026-07-04T17:07:47.694Z" },
{ url = "https://files.pythonhosted.org/packages/7b/15/6c1784ae469640e65db111e9a34b3d0f14d91e8a38b9ce34810ced370dbb/numpy-2.5.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:224ca51130ef7da85bea2191625181cb4f337f9cb64b471f10c1a12aa8b60077", size = 18464252, upload-time = "2026-07-04T17:07:50.684Z" },
{ url = "https://files.pythonhosted.org/packages/94/a8/f98e50356cf167df656c526c2dfeec2d7dde182f2a3da4b458a5938e2776/numpy-2.5.1-cp314-cp314t-win32.whl", hash = "sha256:6eab239876581b2b3c5a242281b6007bbdbcd1c7085d7709bb57c5929b11e6bf", size = 6263298, upload-time = "2026-07-04T17:07:53.445Z" },
{ url = "https://files.pythonhosted.org/packages/72/ac/96ae880cdecad0b3275d9359fcec72667b49a4863c9f12942e43679dda02/numpy-2.5.1-cp314-cp314t-win_amd64.whl", hash = "sha256:83ce9c80d5b521b0d77ddcbe5447c218d247929b6cc056ca5351342accfff0af", size = 12748623, upload-time = "2026-07-04T17:07:55.384Z" },
{ url = "https://files.pythonhosted.org/packages/a1/5a/4d2b1601df3602dba7a14f3348ba9bfe94a18adb428e693df6154c293831/numpy-2.5.1-cp314-cp314t-win_arm64.whl", hash = "sha256:5a6db61f9aaa57e369905c67d852045d3c4f7126405b29d09b19dec118e9c9cb", size = 10697674, upload-time = "2026-07-04T17:07:58.506Z" },
]
[[package]]
name = "opencv-python-headless"
version = "5.0.0.93"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "numpy" },
]
sdist = { url = "https://files.pythonhosted.org/packages/1d/99/76b7c80252aa83c1af16393454aafd125a0287101afe8deb0a6821af0e30/opencv_python_headless-5.0.0.93.tar.gz", hash = "sha256:b82f9831daab90b725c7c1ee1b36cb5732c367096ac76d119e64e14eb70d5f3c", size = 81817738, upload-time = "2026-07-02T07:01:06.039Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/53/7c/8c8097891c509d98cd128493835c95631c80be6a8f37ed9d25716c2e16f1/opencv_python_headless-5.0.0.93-cp37-abi3-macosx_13_0_arm64.whl", hash = "sha256:030ca5e0837a2963ab36ef896baa9767eb8d2b83353fb28af5a521e40dd8756f", size = 48322581, upload-time = "2026-07-02T05:50:34.207Z" },
{ url = "https://files.pythonhosted.org/packages/90/8c/eab2ad388c3cbab2a350c10c2ef19ce6bd099240afc31789032c996bab52/opencv_python_headless-5.0.0.93-cp37-abi3-macosx_14_0_x86_64.whl", hash = "sha256:1e55af3abfb462eeeabe5c775f12bdb36216d8a93a3583d69e6bd6e1d6ba7d00", size = 34782894, upload-time = "2026-07-02T05:51:39.856Z" },
{ url = "https://files.pythonhosted.org/packages/ec/78/afca939f40ffe2b2380bfa86f812b2f7d4acc5a27b27dc41b49cad7ce7b4/opencv_python_headless-5.0.0.93-cp37-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:10818d91510e05c04568ae12b5cd120779c70c01bf897b001a6221fe430df80f", size = 36521085, upload-time = "2026-07-02T06:55:24.429Z" },
{ url = "https://files.pythonhosted.org/packages/2b/97/8170e9819764c47e436c130d3ff6cfb73b58f923eae9d3a03d8982b04aec/opencv_python_headless-5.0.0.93-cp37-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:09a872a157c1376ab922a69bbf22f9a95bcc7b658a9d8b436a60212b02b2eeb4", size = 56563598, upload-time = "2026-07-02T06:55:47.355Z" },
{ url = "https://files.pythonhosted.org/packages/3a/98/1a28a7101e31801042b3098871a74b76c61581d328ef40774ff4edb53a56/opencv_python_headless-5.0.0.93-cp37-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:840bd717c21e5c11cadadc022a823315ea417f961213d06b4df010e019eb16f4", size = 39648433, upload-time = "2026-07-02T06:56:04.255Z" },
{ url = "https://files.pythonhosted.org/packages/9b/21/f6ef335f6e65724aa78b8d792b48d40a48c381715f1e62f5a5049e09d07e/opencv_python_headless-5.0.0.93-cp37-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:ed709fdf9aa0bd1f2ed8549e71d19449b03a675bb581eb292285f6861953be37", size = 61204038, upload-time = "2026-07-02T06:56:41.823Z" },
{ url = "https://files.pythonhosted.org/packages/d0/8f/b8756467ea991449a293797f6b3fa80fcfdd29598a0a60d1cd5715b96e61/opencv_python_headless-5.0.0.93-cp37-abi3-win32.whl", hash = "sha256:c6bcd96b185975ea240d22cfdb15a1f6d080cc95264cfbe2621f21bb144d89b9", size = 35411237, upload-time = "2026-07-02T05:50:12.901Z" },
{ url = "https://files.pythonhosted.org/packages/b8/88/763b967f7efd7226b82c9fae16d560cba049b1f0c036647e65c610fd636e/opencv_python_headless-5.0.0.93-cp37-abi3-win_amd64.whl", hash = "sha256:829717b6a95554f273e49e357cee3b3a2a26b6f4842fbc1bed2b45bdd8f87e0e", size = 43825962, upload-time = "2026-07-02T05:50:09.627Z" },
]
[[package]]
name = "pymupdf"
version = "1.28.0"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "https://files.pythonhosted.org/packages/8e/e9/6d6c5d6c0a3551bffd47681a6240caf941727f195b45593cf20ab36f018f/pymupdf-1.28.0.tar.gz", hash = "sha256:e53f3567403a92da15caa9e7ae0164327fff48817e9f40175367fb9de524258d", size = 87637751, upload-time = "2026-06-29T09:08:47.547Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/c8/b7/88043e38cc7529de070f0c9bd267fa258035cca0b4ad5260536b994594a7/pymupdf-1.28.0-cp310-abi3-macosx_10_15_x86_64.whl", hash = "sha256:892b89ba88e8f98b53133b62877a9dc9b5e7dc6a4aeb837b612db56a8d2e03ac", size = 24597385, upload-time = "2026-06-29T09:03:30.608Z" },
{ url = "https://files.pythonhosted.org/packages/33/f4/23775bbda0781b61fc398cc75079a2b0e64696d8fcf93271748883e9627e/pymupdf-1.28.0-cp310-abi3-macosx_11_0_arm64.whl", hash = "sha256:4d692dcf44d3566ae96bc6f6346c6ad432274a29ba617bf7a9fe18009e24adb4", size = 23828292, upload-time = "2026-06-29T09:03:46.129Z" },
{ url = "https://files.pythonhosted.org/packages/1c/f5/bf75fc7a415722f8b33662054f82d88520c0cbfd4c36d0e08aeaec605e49/pymupdf-1.28.0-cp310-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:47a5c29ed4eb0744de9c4e37bb49b1259b18d4d75fcc8a7c130f7c9fa15956f6", size = 25045507, upload-time = "2026-06-29T09:04:03.86Z" },
{ url = "https://files.pythonhosted.org/packages/58/69/5d12c9f1f2d76f28383d6110a069c79fbfced5a4f97bb1ee6e8354f52bb7/pymupdf-1.28.0-cp310-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:44f0973f5e5edbaec95bc34b64e71d1959d4ee90b1328de1b4f4f5b4fa78673f", size = 25716599, upload-time = "2026-06-29T09:04:19.367Z" },
{ url = "https://files.pythonhosted.org/packages/4d/b4/ec0e017bc42857cc86bd651441dbc41cc18be48d4698ecd27aac491e0c9a/pymupdf-1.28.0-cp310-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:4d61ec323a706e153a12e262e51febfb43eeaa20977785ace135d18d48bcdc83", size = 25940489, upload-time = "2026-06-29T09:04:36.624Z" },
{ url = "https://files.pythonhosted.org/packages/06/86/f831fef09013f33b3c9c09fb3923f2ff53e1e437f6ace14b8ae46392f558/pymupdf-1.28.0-cp310-abi3-win32.whl", hash = "sha256:caea2b3b67347fd79e5d15ed7929b0e886aac594ea228073b6d39de0078189da", size = 18489703, upload-time = "2026-06-29T20:50:30.599Z" },
{ url = "https://files.pythonhosted.org/packages/2e/5d/1a03f53eb0449900469335fcfc742ca28e3ba159b7d650e0921d50b8b308/pymupdf-1.28.0-cp310-abi3-win_amd64.whl", hash = "sha256:e01e90fd86abfeb37ceb921eddb951f988a11d45ff6ce6b7664f2039849068ec", size = 19773102, upload-time = "2026-06-29T09:04:49.773Z" },
{ url = "https://files.pythonhosted.org/packages/72/f6/1e52ce243ca792254f6223b4017c5667194c146ce9b88baf37bc5eb3d1c9/pymupdf-1.28.0-cp313-abi3-pyemscripten_2025_0_wasm32.whl", hash = "sha256:74c6d00ba2a9aad3a635db73b07c15db462b480741d831a34a75a56535ebc22b", size = 18357011, upload-time = "2026-06-29T20:50:50.353Z" },
{ url = "https://files.pythonhosted.org/packages/62/b1/46b5b3d8ef3cc71114667cf10c4d8b33f39af97253af32e9a0986775b638/pymupdf-1.28.0-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:b3e1399c7a64c6914239116a369efcdaac4cfb9e838bde2656d7accc4a85c72d", size = 25753599, upload-time = "2026-06-29T09:05:09.398Z" },
]
[[package]]
name = "pyside6"
version = "6.11.1"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "pyside6-addons" },
{ name = "pyside6-essentials" },
{ name = "shiboken6" },
]
wheels = [
{ url = "https://files.pythonhosted.org/packages/da/a6/27ba5947ed48918f7b74b7c43a1e280aac069e36f25adeb4c9adfac835c4/pyside6-6.11.1-cp310-abi3-macosx_13_0_universal2.whl", hash = "sha256:537682c3b7530817203e667c1f5a2f00486b37bf52c52eeab438544c7a0917f6", size = 571921, upload-time = "2026-05-13T09:47:36.402Z" },
{ url = "https://files.pythonhosted.org/packages/d8/de/af89d71410c83b10654d86ff9aff2a4f87c30163658f1cc145242e222526/pyside6-6.11.1-cp310-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:b1fc521ba2bb5109425ab8add06bddbdd524abcad06cfa012cc39a22a189feb2", size = 572102, upload-time = "2026-05-13T09:47:38.249Z" },
{ url = "https://files.pythonhosted.org/packages/b6/0e/d583bd3f7bf5046a4497b36f3902cfb64aa29554489a5a25c18e6b4ac0ac/pyside6-6.11.1-cp310-abi3-manylinux_2_39_aarch64.whl", hash = "sha256:75f0005c3eb95c07cfb65522ec50d0815ac007a96482c21dc3cb4b4c04895d84", size = 572098, upload-time = "2026-05-13T09:47:39.44Z" },
{ url = "https://files.pythonhosted.org/packages/57/f2/d9d8ce1373dabb37e5919f63cd18446556079631d3f2eea3ada03c29f6b8/pyside6-6.11.1-cp310-abi3-win_amd64.whl", hash = "sha256:0968877ab1fb4ef3587a284da6fe05e8647ada56a6a3750b6395188e01f4aba6", size = 578377, upload-time = "2026-05-13T09:47:40.76Z" },
{ url = "https://files.pythonhosted.org/packages/96/02/a6057d8bd2bdb1940820fff2d627fdf4013148c9c57adf69fa40d3452ac3/pyside6-6.11.1-cp310-abi3-win_arm64.whl", hash = "sha256:acee467cb5f256cc47ebb9d815a054c1d8416da380c191b247a76d164aa3f805", size = 561765, upload-time = "2026-05-13T09:47:41.9Z" },
]
[[package]]
name = "pyside6-addons"
version = "6.11.1"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "pyside6-essentials" },
{ name = "shiboken6" },
]
wheels = [
{ url = "https://files.pythonhosted.org/packages/3f/6b/8bc94aff48b63f788f2d84e5467c12362d68906ba742c0942f46cb04c879/pyside6_addons-6.11.1-cp310-abi3-macosx_13_0_universal2.whl", hash = "sha256:54733c77f789bef5f03c6aff4ad3bec8b2eff021f0cfcbc53d5e6c250ded24f9", size = 331714589, upload-time = "2026-05-13T09:39:12.36Z" },
{ url = "https://files.pythonhosted.org/packages/dd/62/fb1428a523b2a4541e232aab50d9e789e6b4526f37fd9593452a7ea5b6b3/pyside6_addons-6.11.1-cp310-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:8e6c65fbd73a512d6f72cda8d8277444a85a34dc99dd1dae9c21d35b8671bb1f", size = 175063224, upload-time = "2026-05-13T09:39:34.185Z" },
{ url = "https://files.pythonhosted.org/packages/ee/9b/2ccd52f66db55c06de65d0501170a1935d04d64d0a230c0d892284a02ce3/pyside6_addons-6.11.1-cp310-abi3-manylinux_2_39_aarch64.whl", hash = "sha256:bf1c6c4e954e5eba3d2a7c661ad4b9689e8f09c7f4a16bdf29713371d11af993", size = 170553429, upload-time = "2026-05-13T09:39:54.424Z" },
{ url = "https://files.pythonhosted.org/packages/9a/bd/8adc4d350b3b363f3dfc8fccdcf5bfed25f7e36c2fff30c64e106f4f1572/pyside6_addons-6.11.1-cp310-abi3-win_amd64.whl", hash = "sha256:0d13c4dfd671b050a48e4f8d8ddc724b7248f9c0437e7fc47fdf316278572923", size = 168816308, upload-time = "2026-05-13T09:40:13.541Z" },
{ url = "https://files.pythonhosted.org/packages/65/b7/9a840d97f0f0f04e372a87e205dd30ee285b4e3b021b188459a917c9dc76/pyside6_addons-6.11.1-cp310-abi3-win_arm64.whl", hash = "sha256:3494f480dee92f415be2f2d989c0b3f4755ac332b28045cbf4ba0f5c5a22ba37", size = 35759347, upload-time = "2026-05-13T09:40:21.199Z" },
]
[[package]]
name = "pyside6-essentials"
version = "6.11.1"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "shiboken6" },
]
wheels = [
{ url = "https://files.pythonhosted.org/packages/b3/da/10d9197e7370eb4fed8df5fc547b7548dec88e5c5949e2d450db4ae96feb/pyside6_essentials-6.11.1-cp310-abi3-macosx_13_0_universal2.whl", hash = "sha256:228de53c2bc26b07e5021fbe3614fc44ca08e4dab9999af08c2b389d2c239957", size = 110352945, upload-time = "2026-05-13T09:43:08.006Z" },
{ url = "https://files.pythonhosted.org/packages/5c/49/0e1237c4400bec7e335d2c4eeb49bc40d9fd88a9ac44ca9083ce1abdc308/pyside6_essentials-6.11.1-cp310-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:e3ef7027b41e4e55fadb56e3b3257dc8ee92154b639fe67fc4c8e05e9d976c60", size = 79908535, upload-time = "2026-05-13T09:43:24.836Z" },
{ url = "https://files.pythonhosted.org/packages/4c/c5/da4c5f23c6540ac5211a1f60177c8dee84b1bf40f2719479587ab8c60731/pyside6_essentials-6.11.1-cp310-abi3-manylinux_2_39_aarch64.whl", hash = "sha256:a039b6da68a3a4b9d243217b2b98d475eed3f617159ef6be925badab53c11b0d", size = 78960051, upload-time = "2026-05-13T09:43:35.423Z" },
{ url = "https://files.pythonhosted.org/packages/64/0e/b663ecc96ca57b5c91b83b6615d6b174380b0faf30338125c26e053d6aa7/pyside6_essentials-6.11.1-cp310-abi3-win_amd64.whl", hash = "sha256:63311bd48e32c584599ab04b9ef7c324082374cd2c9fa533f978fb893bb47e40", size = 77549267, upload-time = "2026-05-13T09:43:44.92Z" },
{ url = "https://files.pythonhosted.org/packages/f1/12/eb6723faf5cb7fa581145da1c15f40d641b96e080f0491af2f1859fdeedb/pyside6_essentials-6.11.1-cp310-abi3-win_arm64.whl", hash = "sha256:11253ea52aabecefe9febddbbe78b43a824129e3af1cec98431028fba7fa954f", size = 57964512, upload-time = "2026-05-13T09:43:52.968Z" },
]
[[package]]
name = "shiboken6"
version = "6.11.1"
source = { registry = "https://pypi.org/simple" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/17/f3/f2b63df0251e7cd3172ea28e32ede52739de9566bcefcd0178681538ac81/shiboken6-6.11.1-cp310-abi3-macosx_13_0_universal2.whl", hash = "sha256:1a16867f103ef1c662a5f09dfed03273a9f81688b174555162c58e83650a3f02", size = 476874, upload-time = "2026-05-13T09:47:01.091Z" },
{ url = "https://files.pythonhosted.org/packages/c7/9b/e0355d8897b5c150770f1d95718aad17d432fcc9c035c04f3f58427d4693/shiboken6-6.11.1-cp310-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:9a8bccfafc8805254cabcfa1edfaf55cd52889f4998c91ad0d9a4433fb1bcdbe", size = 272222, upload-time = "2026-05-13T09:47:02.653Z" },
{ url = "https://files.pythonhosted.org/packages/57/d5/dd4f1defed400be03340f2ede34b61f846776650b4e7ed9ebaf4c71979a2/shiboken6-6.11.1-cp310-abi3-manylinux_2_39_aarch64.whl", hash = "sha256:1bd2f4314414df2d122d9f646e03b731bc6d6b5f77a5f53f99a4fe4e97d84e6f", size = 270350, upload-time = "2026-05-13T09:47:04.02Z" },
{ url = "https://files.pythonhosted.org/packages/52/b5/3f6fb2ee65b534193fb4ef713dd619dc31dadff5d12c16979a7699ad58be/shiboken6-6.11.1-cp310-abi3-win_amd64.whl", hash = "sha256:c2c6863aa80ec18c0f82cea3417837b279cdc60024ac17123461dc9042577df7", size = 1223647, upload-time = "2026-05-13T09:47:05.924Z" },
{ url = "https://files.pythonhosted.org/packages/98/d1/f15ca0e1666faae02c945f48e745ea35f8fcd8243b176109b4e2c4251f47/shiboken6-6.11.1-cp310-abi3-win_arm64.whl", hash = "sha256:7c8d9af17db4495d4fa5b1c393f218311c4855546b9dfa6a0bd21bcd66b55e9d", size = 1784170, upload-time = "2026-05-13T09:47:07.617Z" },
]