ATONLoader

loader.graphical.aton.ATONLoader()

Load ATON format files (piano roll analysis data).

ATON (Artistic Text-based Object Notation) is a structured text format used by the Stanford SUPRA project for storing piano roll analysis data including hole punch positions and metadata.

The loader parses ROLLINFO metadata and HOLE blocks, providing access to both individual hole data and aggregate statistics.

Examples

>>> from timetoalign.testdata import ensure_data
>>> roll = ensure_data("supra") / "image" / "fd660zf8362_analysis.txt"
>>> loader = ATONLoader().load(roll)
>>> loader.rollinfo['MUSICAL_HOLES']
30092
>>> len(loader.holes)
30092

Hole positions are pixel coordinates on the scanned roll:

>>> loader.first_hole
Coordinate(15343, pixels)
>>> loader.last_hole
Coordinate(293119, pixels)

Attributes

Name	Type	Description
rollinfo	dict[str, Any]	Dictionary of ROLLINFO metadata.
holes	list[ATONHole]	List of parsed ATONHole objects.

Methods

Name	Description
create_timeline	Create a timeline populated with hole events.
from_file	Create a loader and load an ATON file in one step.
get_holes_by_tracker	Get all holes for a specific tracker bar position.
get_holes_in_range	Get holes within a pixel row range.
get_note_holes	Get holes that represent note attacks.
load	Load and parse an ATON file.

create_timeline

loader.graphical.aton.ATONLoader.create_timeline(uid=None, name=None)

Create a timeline populated with hole events.

Creates a graphical timeline (in pixels) spanning the full image height, with all parsed holes as InstantEvents at their absolute pixel coordinates.

This is the primary timeline for the piano roll image. To get a relative coordinate view (first hole = 0), create an inherited DiscreteGraphicalTimeline child at first_hole.

Parameters

Name	Type	Description	Default
uid	str | None	Unique identifier for the timeline. Auto-generated if None.	None
name	str | None	Human-readable name. Uses source filename if None.	None

Returns

Name	Type	Description
	DiscreteGraphicalTimeline	A DiscreteGraphicalTimeline with hole events at absolute coordinates.

Raises

Name	Type	Description
	RuntimeError	If no data has been loaded.

Examples

>>> loader = ATONLoader()
>>> loader.load("analysis.txt")
>>> dgt1 = loader.create_timeline(uid="dgt1")
>>> dgt1.n_events
30092
>>> # Child inherits DiscreteGraphicalTimeline; its origin is the first hole
>>> dgt_holes = dgt1.create_child(
...     length=loader.musical_length,
...     offset=loader.first_hole,
...     uid="dgt_holes",
... )

from_file

loader.graphical.aton.ATONLoader.from_file(path)

Create a loader and load an ATON file in one step.

Convenience constructor for loading a single file.

Parameters

Name	Type	Description	Default
path	Path | str	Path to the ATON file.	required

Returns

Name	Type	Description
	Self	A new ATONLoader instance with the file already loaded.

Examples

>>> loader = ATONLoader.from_file("analysis.txt")
>>> loader.musical_holes
30092

get_holes_by_tracker

loader.graphical.aton.ATONLoader.get_holes_by_tracker(tracker_hole)

Get all holes for a specific tracker bar position.

Parameters

Name	Type	Description	Default
tracker_hole	int	Tracker bar hole number (0-99).	required

Returns

Name	Type	Description
	list[ATONHole]	List of holes at that tracker position.

get_holes_in_range

loader.graphical.aton.ATONLoader.get_holes_in_range(start_row, end_row)

Get holes within a pixel row range.

Parameters

Name	Type	Description	Default
start_row	int	Starting pixel row (inclusive).	required
end_row	int	Ending pixel row (inclusive).	required

Returns

Name	Type	Description
	list[ATONHole]	List of holes with origin_row in range.

get_note_holes

loader.graphical.aton.ATONLoader.get_note_holes()

Get holes that represent note attacks.

Returns

Name	Type	Description
	list[ATONHole]	List of holes with note_attack set.

load

loader.graphical.aton.ATONLoader.load(path)

Load and parse an ATON file.

Parameters

Name	Type	Description	Default
path	Path | str	Path to the ATON file.	required

Returns

Name	Type	Description
	Self	Self, for method chaining.

Raises

Name	Type	Description
	FileNotFoundError	If the file doesn’t exist.
	ValueError	If the file format is invalid.