Module eyekit.tools

Functions for performing common procedures, such as discarding out of bounds fixations and snapping fixations to the lines of text.

Functions

def discard_short_fixations(fixation_sequence, threshold=50)

Given a FixationSequence, discard all fixations that are shorter than some threshold value. Operates directly on the sequence and does not return a copy.

View code on GitHub

def discard_out_of_bounds_fixations(fixation_sequence, text_block, threshold=100)

Given a FixationSequence and TextBlock, discard all fixations that do not fall within some threshold distance of any character in the text. Operates directly on the sequence and does not return a copy.

View code on GitHub

def snap_to_lines(fixation_sequence, text_block, method='warp', **kwargs)

Given a FixationSequence and TextBlock, snap each fixation to the line that it most likely belongs to, eliminating any y-axis variation or drift. Operates directly on the sequence and does not return a copy. Several methods are available, some of which take optional parameters or require SciPy to be installed. For a full description and evaluation of these methods, see Carr et al. (2020).

• chain : Chain consecutive fixations that are sufficiently close to each other, and then assign chains to their closest text lines. Default params: x_thresh=192, y_thresh=32.

• cluster : Classify fixations into m clusters based on their Y-values, and then assign clusters to text lines in positional order. Requires SciPy.

• merge : Form a set of progressive sequences and then reduce the set to m by repeatedly merging those that appear to be on the same line. Merged sequences are then assigned to text lines in positional order. Default params: y_thresh=32, gradient_thresh=0.1, error_thresh=20.

• regress : Find m regression lines that best fit the fixations and group fixations according to best fit regression lines, and then assign groups to text lines in positional order. Default params: slope_bounds=(-0.1, 0.1), offset_bounds=(-50, 50), std_bounds=(1, 20). Requires SciPy.

• segment : Segment fixation sequence into m subsequences based on m–1 most-likely return sweeps, and then assign subsequences to text lines in chronological order.

• split : Split fixation sequence into subsequences based on best candidate return sweeps, and then assign subsequences to closest text lines. Requires SciPy.

• stretch : Find a stretch factor and offset that results in a good alignment between the fixations and lines of text, and then assign the transformed fixations to the closest text lines. Default params: stretch_bounds=(0.9, 1.1), offset_bounds=(-50, 50). Requires SciPy.

• warp : Map fixations to word centers using Dynamic Time Warping. This finds a monotonically increasing mapping between fixations and words with the shortest overall distance, effectively resulting in m subsequences. Fixations are then assigned to the lines that their mapped words belong to, effectively assigning subsequences to text lines in chronological order.

View code on GitHub

def align_to_screenshot(text_block, screenshot_path, output_path=None, show_text=True, show_bounding_boxes=False)

Create an image depicting a PNG screenshot overlaid with a TextBlock in green. If no output path is provided, the output is written to the same directory as the screenshot file. This is useful for establishing the correct TextBlock parameters to match what participants are actually seeing.

View code on GitHub

def font_size_at_72dpi(font_size, at_dpi=96)

Convert a font size at some dpi to the equivalent font size at 72dpi. Typically, this can be used to convert a Windows-style 96dpi font size to the equivalent size at 72dpi.

View code on GitHub