alto.ui.engraving
Drawing notation with SMuFL music fonts (Bravura, Leland, Petaluma, MuseJazz and others).
A SMuFL font has the parts of a note rather than whole notes: the head, the flag, and the clef and accidental glyphs, all measured in staff spaces (four to the em). The stem is a plain rectangle that the code draws, placed using the stem anchors the font publishes for each head. Heights are measured upward, so they are flipped on screen.
Examples
>>> sorted(HEADS)
['breve', 'half', 'whole']
>>> ACCIDENTALS[1]
'accidentalSharp'
staff_line_width
def staff_line_width(
font: str,
*,
gap: float,
) -> float
Return the thickness of a staff line, as the font specifies.
Parameters
font(str): A key of_FILES.gap(float): The distance between staff lines in pixels. Keyword-only.
Returns
- float: The thickness in pixels, at least 1.
Examples
>>> staff_line_width("bravura", gap=16) >= 1.0
True
ledger_width
def ledger_width(
font: str,
*,
gap: float,
) -> float
Return the thickness of a ledger line, as the font specifies.
Parameters
font(str): A key of_FILES.gap(float): The distance between staff lines in pixels. Keyword-only.
Returns
- float: The thickness in pixels, at least 1.2.
Examples
>>> ledger_width("bravura", gap=16) >= 1.2
True
draw_note
def draw_note(
p: QPainter,
*,
font: str,
value: str,
x: float,
y: float,
gap: float,
colour: QColor,
stem_down: bool = False,
) -> None
Draw a note with its head centred on a point.
The head, then a stem and (for the short values) a flag, placed on the font’s anchors.
Parameters
p(QPainter): The painter to draw with.font(str): A key of_FILES. Keyword-only.value(str): “breve”, “whole”, “half”, “quarter”, “eighth”, “sixteenth” or “thirty_second”. Keyword-only.x(float): The head’s centre, in pixels. Keyword-only.y(float): The head’s centre, in pixels. Keyword-only.gap(float): The distance between staff lines in pixels. Keyword-only.colour(QColor): The colour. Keyword-only.stem_down(bool, default False): Draw the stem down. Keyword-only.
Examples
>>> from PySide6.QtGui import QImage
>>> image = QImage(100, 100, QImage.Format.Format_ARGB32)
>>> image.fill(QColor("white"))
>>> painter = QPainter(image)
>>> draw_note(painter, font="bravura", value="eighth", x=50, y=60, gap=16, colour=QColor("black"))
>>> painter.end()
True
>>> image.pixelColor(50, 60).lightness() < 128
True
draw_clef
def draw_clef(
p: QPainter,
*,
font: str,
clef: str,
x: float,
bottom: float,
gap: float,
colour: QColor,
) -> None
Draw a clef with its left edge at a point.
Parameters
p(QPainter): The painter to draw with.font(str): A key of_FILES. Keyword-only.clef(str): “treble”, “bass”, “alto”, “tenor”, “soprano”, “mezzo”, “baritone_c” or “baritone_f”. Keyword-only.x(float): The clef’s left edge, in pixels. Keyword-only.bottom(float): The y position of the staff’s bottom line, in pixels. Keyword-only.gap(float): The distance between staff lines in pixels. Keyword-only.colour(QColor): The colour. Keyword-only.
Examples
>>> from PySide6.QtGui import QImage
>>> image = QImage(100, 100, QImage.Format.Format_ARGB32)
>>> image.fill(QColor("white"))
>>> painter = QPainter(image)
>>> draw_clef(painter, font="bravura", clef="treble", x=10, bottom=70, gap=10, colour=QColor("black"))
>>> painter.end()
True
>>> any(image.pixelColor(x_, y).lightness() < 128 for x_ in range(10, 40) for y in range(20, 90))
True
accidental_width
def accidental_width(
*,
font: str,
sign: int,
gap: float,
) -> float
Return how wide a sharp, flat or natural is drawn, so that it can be placed beside other things.
Parameters
font(str): A key of_FILES. Keyword-only.sign(int): -2 for a double flat, -1 flat, 0 natural, 1 sharp or 2 double sharp. Keyword-only.gap(float): The distance between staff lines in pixels, which sets the size. Keyword-only.
Returns
- float: The width of the glyph’s ink, in pixels.
Examples
>>> accidental_width(font="bravura", sign=1, gap=16) > accidental_width(font="bravura", sign=1, gap=8)
True
draw_accidental
def draw_accidental(
p: QPainter,
*,
font: str,
sign: int,
x: float,
y: float,
gap: float,
colour: QColor,
fit: float | None = None,
) -> float
Draw a sharp, flat or natural with its left edge at a point.
Parameters
p(QPainter): The painter to draw with.font(str): A key of_FILES. Keyword-only.sign(int): -2 for a double flat, -1 flat, 0 natural, 1 sharp or 2 double sharp. Keyword-only.x(float): The glyph’s left edge, in pixels. Keyword-only.y(float): The glyph’s reference line, in pixels. Keyword-only.gap(float): The distance between staff lines in pixels. Keyword-only.colour(QColor): The colour. Keyword-only.fit(float or None, default None): If given, shrink the glyph to be no wider than this many pixels. Keyword-only.
Returns
- float: The width drawn, in pixels.
Examples
>>> from PySide6.QtGui import QImage
>>> image = QImage(100, 100, QImage.Format.Format_ARGB32)
>>> painter = QPainter(image)
>>> normal = draw_accidental(painter, font="bravura", sign=1, x=10, y=50, gap=16, colour=QColor("black"))
>>> squeezed = draw_accidental(painter, font="bravura", sign=1, x=10, y=50, gap=16, colour=QColor("black"), fit=5.0)
>>> painter.end()
True
>>> squeezed <= 5.0 < normal
True
draw_brace
def draw_brace(
p: QPainter,
*,
font: str,
x: float,
y0: float,
y1: float,
colour: QColor,
width: float,
) -> bool
Draw the font’s brace stretched between two heights, for a grand staff.
Parameters
p(QPainter): The painter to draw with.font(str): A key of_FILES. Keyword-only.x(float): The brace’s right edge, in pixels. Keyword-only.y0(float): The top, in pixels. Keyword-only.y1(float): The bottom, in pixels. Keyword-only.colour(QColor): The colour. Keyword-only.width(float): How wide to draw it, in pixels. Keyword-only.
Returns
- bool: True if it was drawn; False (and nothing is drawn) if the font has no usable brace.
Examples
>>> from PySide6.QtGui import QImage
>>> image = QImage(100, 100, QImage.Format.Format_ARGB32)
>>> painter = QPainter(image)
>>> draw_brace(painter, font="bravura", x=30, y0=10, y1=90, colour=QColor("black"), width=12)
True
>>> painter.end()
True