GraphicalLoader

loader.graphical.GraphicalLoader(metadata=None)

Factory for building GraphicalStore objects.

The loader accumulates sources and segments, then builds a store. This provides a fluent interface for constructing graphical timelines.

Examples

>>> loader = GraphicalLoader()
>>> idx = loader.add_image("score.png")
>>> loader.add_horizontal_segment(idx, x0=10, x1=500, y=100, name="system_1")
>>> loader.add_horizontal_segment(idx, x0=10, x1=500, y=200, name="system_2")
>>> store = loader.store

>>> # From PDF
>>> import pymupdf
>>> doc = pymupdf.open("score.pdf")
>>> loader = GraphicalLoader()
>>> idx = loader.add_pdf_page(doc, 0)
>>> loader.add_horizontal_segment(idx, x0=50, x1=550, y=100, name="page1")

Attributes

Name	Type	Description
metadata	`dict`[`str`, `Any`]	Optional metadata dictionary attached to the store.

Methods

Name	Description
add_horizontal_segment	Add a horizontal line segment (convenience method).
add_image	Add an image file as a source.
add_image_source	Add a pre-constructed ImageSource.
add_pdf_embedded_image	Add an embedded PDF image as a source.
add_pdf_page	Add a PDF page (rendered as image) as a source.
add_segment	Add a segment with arbitrary path.
add_vertical_segment	Add a vertical line segment (convenience method).
build	Alias for :pyattr:`store`.
clear	Clear all sources and segments.
reset_offset	Reset the current offset for contiguous segment addition.

add_horizontal_segment

loader.graphical.GraphicalLoader.add_horizontal_segment(
    source_index,
    x0,
    x1,
    y,
    name=None,
    offset=None,
    tolerance=10.0,
)

Add a horizontal line segment (convenience method).

This is the most common case for musical scores and spectrograms.

Parameters

Name	Type	Description	Default
source_index	`int`	Index of the source image.	required
x0	`float`	Starting x coordinate (left edge).	required
x1	`float`	Ending x coordinate (right edge).	required
y	`float`	Fixed y coordinate (vertical position).	required
name	`str` \| None	Optional human-readable name.	`None`
offset	`float` \| None	Timeline offset. If None, appends contiguously.	`None`
tolerance	`float`	Distance tolerance for coordinate conversion.	`10.0`

Returns

Name	Type	Description
	`GraphicalSegment`	The created GraphicalSegment.

add_image

loader.graphical.GraphicalLoader.add_image(path)

Add an image file as a source.

Parameters

Name	Type	Description	Default
path	`Path` \| `str`	Path to the image file.	required

Returns

Name	Type	Description
	`int`	Index of the added source (for use in add_segment).

Raises

Name	Type	Description
	`FileNotFoundError`	If file doesn’t exist.
	`ValueError`	If format is not supported.

add_image_source

loader.graphical.GraphicalLoader.add_image_source(source)

Add a pre-constructed ImageSource.

Parameters

Name	Type	Description	Default
source	`ImageSource`	The ImageSource to add.	required

Returns

Name	Type	Description
	`int`	Index of the added source.

add_pdf_embedded_image

loader.graphical.GraphicalLoader.add_pdf_embedded_image(doc, xref)

Add an embedded PDF image as a source.

Parameters

Name	Type	Description	Default
doc	'pymupdf.Document'	An open pymupdf Document.	required
xref	`int`	Cross-reference number of the image.	required

Returns

Name	Type	Description
	`int`	Index of the added source.

add_pdf_page

loader.graphical.GraphicalLoader.add_pdf_page(doc, page_index, dpi=150)

Add a PDF page (rendered as image) as a source.

Parameters

Name	Type	Description	Default
doc	'pymupdf.Document'	An open pymupdf Document.	required
page_index	`int`	Zero-based page index.	required
dpi	`int`	Resolution for rendering.	`150`

Returns

Name	Type	Description
	`int`	Index of the added source.

add_segment

loader.graphical.GraphicalLoader.add_segment(
    source_index,
    path,
    name=None,
    offset=None,
)

Add a segment with arbitrary path.

Parameters

Name	Type	Description	Default
source_index	`int`	Index of the source image.	required
path	`TimeAxisPath`	TimeAxisPath defining the time axis geometry.	required
name	`str` \| None	Optional human-readable name.	`None`
offset	`float` \| None	Timeline offset. If None, appends contiguously.	`None`

Returns

Name	Type	Description
	`GraphicalSegment`	The created GraphicalSegment.

Raises

Name	Type	Description
	`IndexError`	If source_index is invalid.

add_vertical_segment

loader.graphical.GraphicalLoader.add_vertical_segment(
    source_index,
    x,
    y0,
    y1,
    name=None,
    offset=None,
    tolerance=10.0,
)

Add a vertical line segment (convenience method).

Parameters

Name	Type	Description	Default
source_index	`int`	Index of the source image.	required
x	`float`	Fixed x coordinate.	required
y0	`float`	Starting y coordinate (top).	required
y1	`float`	Ending y coordinate (bottom).	required
name	`str` \| None	Optional human-readable name.	`None`
offset	`float` \| None	Timeline offset. If None, appends contiguously.	`None`
tolerance	`float`	Distance tolerance for coordinate conversion.	`10.0`

Returns

Name	Type	Description
	`GraphicalSegment`	The created GraphicalSegment.

build

loader.graphical.GraphicalLoader.build()

Alias for :pyattr:store.

Returns

Name	Type	Description
	`GraphicalStore`	GraphicalStore containing all sources and segments.

clear

loader.graphical.GraphicalLoader.clear()

Clear all sources and segments.

reset_offset

loader.graphical.GraphicalLoader.reset_offset(offset=0.0)

Reset the current offset for contiguous segment addition.

Parameters

Name	Type	Description	Default
offset	`float`	New offset value (default 0.0).	`0.0`