API Reference

Public package

TachyPy public API with lazy imports to avoid unnecessary backend loading.

Core modules

Display and timing utilities for TachyPy with pluggable backends.

class tachypy.screen.Screen(screen_number: int = 0, width: int | None = None, height: int | None = None, fullscreen: bool = True, vsync: bool = True, desired_refresh_rate: int = 60, grab_input: bool = True, backend: str = 'glfw')

Create and manage a display backed by Pygame or GLFW.

close() → None

Close the display backend.

fill(color: Sequence[float] = (128, 128, 128)) → None

Clear the screen with the provided RGB color in [0, 255].

flip() → int

Swap buffers and return the immediate post-swap timestamp in nanoseconds.

The returned value is captured immediately after the backend swap call returns, before event polling, viewport synchronization, input updates, or frame-rate housekeeping. It approximates the display swap completion time, not photon onset at a specific screen location.

get_flip_interval() → float | None

Return the interval between the last two flips in seconds.

get_mouse_position() → Tuple[float, float] | None

Return current mouse position for GLFW backend, otherwise None.

hide_mouse() → None

Hide cursor in the active backend window.

is_key_down(key) → bool

Return True when key is currently held (GLFW backend only).

is_mouse_button_pressed(button_index: int) → bool

Return True when the mouse button is currently pressed (GLFW only).

set_mouse_position(x: float, y: float) → None

Set cursor position for active backend window.

set_mouse_visible(visible: bool) → None

Set mouse visibility explicitly.

should_close() → bool

Return close status for GLFW windows; always False for pygame.

show_mouse() → None

Show cursor in the active backend window.

test_flip_intervals(num_frames: int = 50) → float

Measure and return the mean frame interval in seconds.

tick() → None

Limit frame updates to the desired refresh rate.

wait(duration_secs: float) → None

Wait for a duration in seconds using high precision timing.

was_key_pressed(key) → bool

Return True when key transitioned to down this frame (GLFW only).

was_mouse_button_pressed(button_index: int) → bool

Return True when the mouse button transitioned to down this frame.

was_mouse_button_released(button_index: int) → bool

Return True when the mouse button transitioned to up this frame.

class tachypy.responses.ResponseHandler(keys_to_listen=None, screen=None)

Process keyboard and mouse input events from Pygame or GLFW screen backend.

clear_events()

Clear tracked key/mouse states and pending framework events.

get_events()

Retrieve and process events, updating internal state.

get_key_presses()

Return recorded key transition events.

get_mouse_clicks()

Return recorded mouse button transition events.

get_mouse_position()

Return the latest mouse position or None if unavailable.

is_key_down(key_name)

Return True when the given key is currently held.

is_mouse_button_pressed(button)

Return True when the given mouse button index is pressed.

reset_timer()

Reset the event timestamp origin.

set_position(x, y)

Set mouse position (pygame) or tracked logical position (glfw).

should_quit()

Return whether a quit signal has been received.

was_key_pressed(key_name)

Return True when the given key transitioned to down this frame.

class tachypy.audio.Audio(sample_rate=44100, channels=1, backend=None)

Scheduled audio playback wrapper with pluggable backend support.

close()

Close audio resources by stopping playback.

play(data, when=0)

Plays a NumPy array as audio at a specified time. :param data: NumPy array of audio data. :param when: Absolute time in seconds (monotonic) when playback should start.

stop()

Stop current playback immediately.

class tachypy.text.Text(text, font_name='Helvetica', font_size=24, color=(255, 255, 255), dest_rect=None, line_spacing=4, backend='auto')

OpenGL text object with pluggable font backends and texture upload.

delete()

Delete the OpenGL texture associated with this text object.

draw()

Draw the text on the screen, centered within the dest_rect.

set_dest_rect(dest_rect)

Update the destination rectangle and regenerate the surface if needed.

set_text(new_text)

Update the text and regenerate the surface and texture.

class tachypy.text.TextBox(position, size, font, text_color=(0, 0, 0), box_color=(255, 255, 255), border_color=(0, 0, 0), border_thickness=2)

A class to create an interactive text input box for user input.

position

The (x, y) position of the top-left corner of the text box.

Type:

tuple

size

The (width, height) dimensions of the text box.

Type:

tuple

font

The font used for rendering text.

Type:

pygame.font.Font

text_color

RGB color of the input text.

Type:

tuple

box_color

RGB color of the text box background.

Type:

tuple

border_color

RGB color of the text box border.

Type:

tuple

border_thickness

Thickness of the border in pixels.

Type:

int

text

The current text input by the user.

Type:

str

submitted

Flag indicating whether the user has submitted the text.

Type:

bool

cursor_position

The position of the cursor within the text.

Type:

int

clear()

Clear the text box content and reset the submitted flag.

draw()

Draw the text box, including the background, border, text, and cursor.

draw_cursor()

Draw the cursor at the appropriate position.

handle_event(event)

Handle Pygame events related to text input.

Parameters:

event (pygame.event.Event) – A Pygame event object.

update(delta_time)

Update the text box, handling cursor blinking.

Parameters:

delta_time (float) – Time elapsed since the last update in milliseconds.

update_texture()

Update the OpenGL texture with the current text.

Backend-independent OpenGL bitmap text rendering.

class tachypy.gltext.GLText(text: str, dest_rect=None, color: Sequence[float] = (255, 255, 255), pixel_size: float = 3.0, line_spacing: float = 2.0, glyph_spacing: float = 1.0, align: str = 'center', vertical_align: str = 'center')

Draw simple bitmap text directly with OpenGL quads.

draw()

Draw the bitmap text block using immediate-mode OpenGL quads.

set_dest_rect(dest_rect)

Update destination rectangle and recompute line wrapping.

set_text(new_text: str)

Update displayed text and recompute line wrapping.

Signed-distance-field text rendering with OpenGL shaders.

class tachypy.gltext_sdf.GLTextSDF(text: str, dest_rect=None, color: Sequence[float] = (255, 255, 255), pixel_size: float = 4.0, line_spacing: float = 2.0, glyph_spacing: float = 1.0, align: str = 'center', vertical_align: str = 'center', sdf_scale: int = 8, sdf_padding: int = 6, sdf_spread: float = 10.0, smoothing: float = 0.1)

Draw higher-quality scalable text using an SDF texture atlas.

delete()

Release OpenGL resources owned by this SDF text object.

draw()

Draw text using the SDF atlas and shader smoothing.

System-font OpenGL text rendering (FreeType + HarfBuzz) with graceful fallback.

class tachypy.glsystemtext.GLSystemText(text: str, dest_rect=None, font_name: str = 'Helvetica', font_size: float = 32.0, color: Sequence[float] = (255, 255, 255), line_spacing: float = 1.15, align: str = 'center', vertical_align: str = 'center', fallback_renderer: str = 'bitmap')

Render text with system TrueType/OpenType fonts and OpenGL quads.

Falls back to GLText when shaping/rasterization dependencies are missing.

delete()

Release allocated glyph textures and fallback resources.

draw()

Draw text, delegating to fallback renderer when system path is disabled.

classmethod resolve_font_path(font_name: str) → Path | None

Resolve a system font from a family/path query.

Supports: - absolute/relative font file paths - comma-separated fallback font families (e.g. “Avenir, Helvetica, Arial”) - partial family/style matching against system font file names

set_dest_rect(dest_rect)

Update destination layout rectangle.

set_text(new_text: str)

Update content text.

tachypy.psychophysics.fabriquer_cercles_sin(nx, frequence, phase)

Deprecated alias for make_concentric_sine_circles().

tachypy.psychophysics.fabriquer_enveloppe_gaussienne(nx, ecart_type)

Deprecated alias for make_gaussian_envelope().

tachypy.psychophysics.fabriquer_gabor(nx, frequence, phase, angle, ecart_type)

Deprecated alias for make_gabor().

tachypy.psychophysics.fabriquer_grand_damier(une_case, M, N)

Deprecated alias for make_checkerboard().

tachypy.psychophysics.fabriquer_grille_sin(nx, frequence, phase, angle)

Deprecated alias for make_sine_grating().

tachypy.psychophysics.fabriquer_petit_damier(une_case)

Deprecated alias for make_checkerboard_tile().

tachypy.psychophysics.fabriquer_secteurs_sin(nx, frequence, phase)

Deprecated alias for make_sine_sectors().

tachypy.psychophysics.fabriquer_wiggles_sin(nx, frequence_min, frequence_max, frequence_radiale, phase_radiale, phase)

Deprecated alias for make_wiggles_sine().

tachypy.psychophysics.location_bubbles(nb_bubbles=50, std_bubble=25, an_image=None, x_size=None, y_size=None, random_state=None)

Generate a bubbles mask and optionally apply it to an image.

Parameters:

• nb_bubbles (int) – Expected number of bubbles.

• std_bubble (float) – Standard deviation of each bubble in pixels.

• an_image (ndarray, optional) – Optional image with values in [0, 1].

• x_size (int, optional) – Image dimensions when an_image is not provided.

• y_size (int, optional) – Image dimensions when an_image is not provided.

• random_state (tuple, optional) – Numpy random state as returned by np.random.get_state().

tachypy.psychophysics.make_checkerboard(num_pixels_per_cell, n_rows, n_cols)

Create a checkerboard image made of repeated 2x2 checkerboard tiles.

tachypy.psychophysics.make_checkerboard_tile(num_pixels_per_cell)

Create a 2x2 checkerboard tile.

tachypy.psychophysics.make_concentric_sine_circles(nx, frequency, phase)

Create concentric sine circles with values in [0, 1].

tachypy.psychophysics.make_gabor(nx, frequency, phase, angle, std_dev)

Create a Gabor patch image with values in [0, 1].

tachypy.psychophysics.make_gaussian_envelope(nx, std_dev)

Create a centered square Gaussian envelope image with values in [0, 1].

tachypy.psychophysics.make_sine_grating(nx, frequency, phase, angle)

Create a square sine grating image with values in [0, 1].

tachypy.psychophysics.make_sine_sectors(nx, frequency, phase)

Create angular sine sectors with values in [0, 1].

tachypy.psychophysics.make_wiggles_sine(nx, frequency_min, frequency_max, radial_frequency, radial_phase, phase)

Create a square “wiggles” image with values in [0, 1].

tachypy.psychophysics.noisy_bit_dithering(im, depth=256)

Implement noisy-bit dithering from Allard & Faubert (2008).

Parameters:

• im (ndarray) – Input image matrix with values expected in [0, 1].

• depth (int) – Number of display levels (default 256).

tachypy.psychophysics.normalize_to_unit_interval(im)

Normalize an array to [0, 1], returning zeros for constant arrays.

tachypy.psychophysics.stretch(im)

Deprecated alias for normalize_to_unit_interval().