RenderOptions

class maelzel.scoring.render.RenderOptions(orientation='portrait', staffSize=12.0, pageSize='a4', pageMarginMillimeters=4, divsPerSemitone=4, showCents=False, centsAnnotationPlacement='above', centsAnnotationFontsize=10, centsAnnotationSeparator=',', centsAnnotationSnap=2, centsAnnotationPlusSign=False, noteLabelStyle='fontsize=10', glissAllowNonContiguous=False, glissHideTiedNotes=True, horizontalSpacing='large', pngResolution=200, removeSuperfluousDynamics=True, restsResetDynamics=True, respellPitches=True, glissLineThickness=1, glissLineType='solid', renderFormat='', cropToContent=None, preview=False, opaque=True, articulationInsideTie=True, dynamicInsideTie=True, rehearsalMarkStyle='box=square; bold; fontsize=13', measureAnnotationStyle='box=rectangle; fontsize=12', enharmonicGroupSize=6, enharmonicStep=3, enharmonicDebug=False, enharmonicHorizontalWeight=1.0, enharmonicVerticalWeight=0.05, enharmonicThreeQuarterMicrotonePenalty=100, backend='lilypond', title='', composer='', lilypondPngStaffsizeScale=1.4, lilypondGlissandoMinimumLength=5, lilypondBinary='', musescoreBinary='', musicxmlSolidSlideGliss=True, musicxmlIndent='  ', musicxmlFontScaling=1.0, referenceStaffsize=12.0, musicxmlTenths=40, autoClefChanges=False, autoClefChangesWindow=1, keepClefBiasFactor=2.0, compoundMeterSubdivision='all', addSubdivisionsForSmallDenominators=True, proportionalSpacing=False, proportionalNotationDuration='1/20', proportionalSpacingKind='strict', flagStyle='normal')

Bases: object

Holds all options needed for rendering

Attributes Summary

addSubdivisionsForSmallDenominators	Add subdivisions for measures with a time signature with a small denominator
articulationInsideTie	Render articulations even if the note is tied
autoClefChanges	If True, add clef changes if necessary along a part during the rendering process
autoClefChangesWindow	When adding automatic clef changes, use this window size (number of elements per evaluation)
backend	Backend used for rendering (lilypond | musicxml)
centsAnnotationFontsize	Fontsize of the cents text annotation
centsAnnotationPlacement	Placement of the cents text annotation (above | below)
centsAnnotationPlusSign	Show a plus sign for possitive cents annotations
centsAnnotationSeparator	Separator for cents annotations to be used in chords
centsAnnotationSnap	No cents annotation is added to a pitch if it is within this number of cents from the nearest microtone accoring to divsPerSemitone
composer	The composer of this score
compoundMeterSubdivision	Sets the subdivision policy for compound meters.
cropToContent	Crop the rendered image to the contexts
divsPerSemitone	Number of divisions of the semitone
dynamicInsideTie	Render dynamics if the note is tied
enharmonicDebug	If True, show debug information regarding the enharmonic spelling process
enharmonicGroupSize	How much horizontal context to take into consideration when finding the best enharmonic spelling
enharmonicHorizontalWeight	The weight of the horizontal dimension during the enharmonic spelling process
enharmonicStep	The step size of the window when evaluating the best enharmonic spelling
enharmonicThreeQuarterMicrotonePenalty	Penalty for spelling a note using three quarter microtones
enharmonicVerticalWeight	The weight of the vertical dimension during the enharmonic spelling process
flagStyle	Flag style, one of 'normal', 'straight', 'flat'
glissAllowNonContiguous	Allow non contiguous gliss
glissHideTiedNotes	Hide the notehead of intermediate notes within a glissando
glissLineThickness	Thickness of the glissando line
glissLineType	Line type used in a glissando (solid | wavy)
horizontalSpacing	The horizontal spacing (large | medium | small).
keepClefBiasFactor	The higher this value, the more priority is given to keeping the previous clef
lilypondBinary	The lilypond binary used
lilypondGlissandoMinimumLength	Mininum length of the glissando line when rendering with lilypond.
lilypondPngStaffsizeScale	Png staffsize scaling when rendering to lilypond
measureAnnotationStyle	Style used for measure annotations
musescoreBinary	The musescore binary
musicxmlFontScaling	A scaling factor applied to fontsize when rendering to musicxml
musicxmlIndent	The indentation used when rendering the xml in musicxml
musicxmlSolidSlideGliss	If True, use a solid slide line for glissando in musicxml
musicxmlTenths	Tenths used when rendering to musicxml.
noteLabelStyle	Style applied to labels
opaque	Remove any transparency in the background (when rendering to png)
orientation	One of portrait, landscape
pageMarginMillimeters	Page margin in mm
pageSize	The page size, on of a1, a2, a3, a4, a5
parsedMeasureAnnotationStyle	Parses the measure annotation style
parsedRehearsalMarkStyle	The style for rehearsal marks, parsed
pngResolution	DPI resolution of generated png images
preview	Only render a preview (only the first system)
proportionalNotationDuration	A lower value results in a note taking more horizontal space
proportionalSpacing	Use proportional spacing
proportionalSpacingKind
referenceStaffsize	The reference staff size.
rehearsalMarkStyle	Text style used for rehearsal marks
removeSuperfluousDynamics	If True, remove superfluous dynamics
renderFormat	The format renderer (pdf | png)
respellPitches	Find the best enharmonic representation
restsResetDynamics	A rest resets the dynamic context so that a dynamic which is the same as the current dynamic will still be rendered after a rest
showCents	Show cents deviation as a text annotation
staffSize	The size of each staff, in points
title	The title of this score

Methods Summary

check()	Check that the options are valid
clone(**changes)	Clone this RenderOptions with the given changes
copy()	Copy this object
keys()	rtype: set[str]
makeEnharmonicOptions()	Create enharmonic options from this RenderOptions
musicxmlTenthsScaling()	Maps mm to tenths when rendering musicxml
pageSizeMillimeters()	Returns the page size in millimeters
parseTextStyle(style)	Parses a textstyle (measureAnnotatioNStyle, rehearsalMarkStyle, ...)

Attributes Documentation

addSubdivisionsForSmallDenominators: bool = True

Add subdivisions for measures with a time signature with a small denominator

A small denominator depends on tempo

articulationInsideTie: bool = True

Render articulations even if the note is tied

autoClefChanges: bool = False

If True, add clef changes if necessary along a part during the rendering process

autoClefChangesWindow: int = 1

When adding automatic clef changes, use this window size (number of elements per evaluation)

backend: str = 'lilypond'

Backend used for rendering (lilypond | musicxml)

centsAnnotationFontsize: int | float = 10

Fontsize of the cents text annotation

centsAnnotationPlacement: str = 'above'

Placement of the cents text annotation (above | below)

centsAnnotationPlusSign: bool = False

Show a plus sign for possitive cents annotations

centsAnnotationSeparator: str = ','

Separator for cents annotations to be used in chords

centsAnnotationSnap: int = 2

No cents annotation is added to a pitch if it is within this number of cents from the nearest microtone accoring to divsPerSemitone

composer: str = ''

The composer of this score

compoundMeterSubdivision: str = 'all'

Sets the subdivision policy for compound meters. One of ‘all’, ‘none’, ‘heterogeneous’

• ‘all’: add subdivisions to all internal subdivisions.

• ‘none’: do not add any subdivision, let the backend decide

• ‘heterogeneous’: add only subdivisions for compound meters with multiple denominators,

  like 3/4+3/8

cropToContent: bool | None = None

Crop the rendered image to the contexts

divsPerSemitone: int = 4

Number of divisions of the semitone

dynamicInsideTie: bool = True

Render dynamics if the note is tied

enharmonicDebug: bool = False

If True, show debug information regarding the enharmonic spelling process

enharmonicGroupSize: int = 6

How much horizontal context to take into consideration when finding the best enharmonic spelling

enharmonicHorizontalWeight: float = 1.0

The weight of the horizontal dimension during the enharmonic spelling process

enharmonicStep: int = 3

The step size of the window when evaluating the best enharmonic spelling

enharmonicThreeQuarterMicrotonePenalty: float = 100

Penalty for spelling a note using three quarter microtones

enharmonicVerticalWeight: float = 0.05

The weight of the vertical dimension during the enharmonic spelling process

flagStyle: str = 'normal'

Flag style, one of ‘normal’, ‘straight’, ‘flat’

glissAllowNonContiguous: bool = False

Allow non contiguous gliss

glissHideTiedNotes: bool = True

Hide the notehead of intermediate notes within a glissando

glissLineThickness: int = 1

Thickness of the glissando line

glissLineType: str = 'solid'

Line type used in a glissando (solid | wavy)

horizontalSpacing: str = 'large'

The horizontal spacing (large | medium | small). Only used by lilypond backend

keepClefBiasFactor: float = 2.0

The higher this value, the more priority is given to keeping the previous clef

lilypondBinary: str = ''

The lilypond binary used

lilypondGlissandoMinimumLength: int = 5

Mininum length of the glissando line when rendering with lilypond. This is to avoid too short glissandi actually not showing at all

lilypondPngStaffsizeScale: float = 1.4

Png staffsize scaling when rendering to lilypond

measureAnnotationStyle: str = 'box=rectangle; fontsize=12'

Style used for measure annotations

musescoreBinary: str = ''

The musescore binary

musicxmlFontScaling: float = 1.0

A scaling factor applied to fontsize when rendering to musicxml

musicxmlIndent: str = '  '

The indentation used when rendering the xml in musicxml

musicxmlSolidSlideGliss: bool = True

If True, use a solid slide line for glissando in musicxml

musicxmlTenths: int = 40

Tenths used when rendering to musicxml. This is a reference value

noteLabelStyle: str = 'fontsize=10'

Style applied to labels

opaque: bool = True

Remove any transparency in the background (when rendering to png)

orientation: str = 'portrait'

One of portrait, landscape

pageMarginMillimeters: int = 4

Page margin in mm

pageSize: str = 'a4'

The page size, on of a1, a2, a3, a4, a5

parsedMeasureAnnotationStyle

Parses the measure annotation style

Returns:

a TextStyle

parsedRehearsalMarkStyle

The style for rehearsal marks, parsed

Returns:

a maelzel.scoring.textstyle.TextStyle

pngResolution: int = 200

DPI resolution of generated png images

preview: bool = False

Only render a preview (only the first system)

proportionalNotationDuration: str = '1/20'

A lower value results in a note taking more horizontal space

proportionalSpacing: bool = False

Use proportional spacing

proportionalSpacingKind: str = 'strict'

referenceStaffsize: float = 12.0

The reference staff size. This is used to convert staffsize to a scaling factor

rehearsalMarkStyle: str = 'box=square; bold; fontsize=13'

Text style used for rehearsal marks

removeSuperfluousDynamics: bool = True

If True, remove superfluous dynamics

renderFormat: str = ''

The format renderer (pdf | png)

respellPitches: bool = True

Find the best enharmonic representation

restsResetDynamics: bool = True

A rest resets the dynamic context so that a dynamic which is the same as the current dynamic will still be rendered after a rest

showCents: bool = False

Show cents deviation as a text annotation

staffSize: int | float = 12.0

The size of each staff, in points

title: str = ''

The title of this score

Methods Documentation

check()

Check that the options are valid

raises ValueError if an error is found

Return type:

None

clone(**changes)

Clone this RenderOptions with the given changes

Parameters:

**changes – any attribute accepted by this RenderOptions

Return type:

RenderOptions

Returns:

a new RenderOptions with the changes applied

Example

>>> defaultoptions = RenderOptions()
>>> modified = defaultoptions.clone(pageSize='A3')

copy()

Copy this object

Return type:

RenderOptions

Returns:

a copy of this RenderOptions

classmethod keys()

Return type:

set[str]

makeEnharmonicOptions()

Create enharmonic options from this RenderOptions

Return type:

EnharmonicOptions

Returns:

an EnharmonicOptions object derived from this RenderOptions

musicxmlTenthsScaling()

Maps mm to tenths when rendering musicxml

The scaling is based on the staff size. This allows to use one setting for all backends

Return type:

tuple[float, int]

pageSizeMillimeters()

Returns the page size in millimeters

Return type:

tuple[float, float]

Returns:

a tuple (height, width), where both height and width are measured in millimeters

static parseTextStyle(style)

Parses a textstyle (measureAnnotatioNStyle, rehearsalMarkStyle, …)

Parameters:

style (str) – the style to parse

Return type:

TextStyle

Returns:

a TextStyle