Module `eyekit.vis`

Defines the Image, Figure, and Booklet objects, which are used to create visualizations.

Functions

def set_default_font(font_face=None, font_size=None): Set the default font face and/or size that will be used in figure captions and image annotations. This selection can be overridden on a per-image or per-figure basis. If no font is set, Eyekit defaults to 8pt Arial.

View code on GitHub

Classes

class Image (screen_width: int, screen_height: int)

The Image class is used to create visualizations of text blocks and fixation sequences, and it provides methods for drawing various kinds of annotation. The general usage pattern is:

img = eyekit.vis.Image(1920, 1080)
img.draw_text_block(txt)
img.draw_fixation_sequence(seq)
img.save('image.pdf')

Initialized with:

screen_width Width of the screen in pixels.
screen_height Height of the screen in pixels.

View code on GitHub

Methods

def set_caption(self, caption, font_face=None, font_size=None): Set the image's caption, which will be shown above the image if you place it inside a Figure.

View code on GitHub
def set_background_color(self, color): Set the background color of the image. By default the background color is white. If color is set to None, the background will be transparent.

View code on GitHub
def draw_text_block(self, text_block, color='black'): Draw a TextBlock on the image. color sets the color of the text.

View code on GitHub
def draw_text_block_heatmap(self, text_block, distribution, color='red'): Draw a TextBlock on the image along with an associated distribution, which is represented in heatmap form. This is can be used to visualize the output from duration_mass(). color determines the color of the heatmap.

View code on GitHub
def draw_fixation_sequence(self, fixation_sequence, show_saccades=True, show_discards=False, color='black', discard_color='gray', number_fixations=False, fixation_radius=None): Draw a FixationSequence on the image. Optionally, you can choose whether or not to display saccade lines and discarded fixations, and which colors to use. number_fixations is not yet implemented. fixation_radius can be used to set a constant radius for all fixations (rather than a radius that is proportional to duration).

View code on GitHub
def draw_sequence_comparison(self, reference_sequence, fixation_sequence, color_match='black', color_mismatch='red', fixation_radius=None): Draw a FixationSequence on the image with the fixations colored according to whether or not they match a reference sequence in terms of the y-coordinate. This is mostly useful for comparing the outputs of two different drift correction algorithms.

View code on GitHub
def draw_line(self, start_xy, end_xy, color='black', stroke_width=1, dashed=False): Draw an arbitrary line on the image from start_xy to end_xy. stroke_width is set in points for vector output or pixels for PNG output.

View code on GitHub
def draw_circle(self, x, y, radius, color='black', stroke_width=1, dashed=False, fill_color=None): Draw an arbitrary circle on the image centered at x, y and with some radius. stroke_width is set in points for vector output or pixels for PNG output.

View code on GitHub
def draw_rectangle(self, rect, y=None, width=None, height=None, color='black', stroke_width=1, dashed=False, fill_color=None): Draw an arbitrary rectangle on the image. rect should be a tuple specifying x, y, width, and height, or these four values can be passed in separately as the first four arguments. stroke_width is set in points for vector output or pixels for PNG output.

View code on GitHub
def draw_annotation(self, x, y, text, font_face=None, font_size=None, color='black'): Draw arbitrary text on the image located at x, y. font_size is set in points for vector output or pixels for PNG output.

View code on GitHub
def save(self, output_path, width=150, crop_margin=None): Save the image to some output_path. Images can be saved as .pdf, .eps, .svg, or .png. width only applies to the vector formats and determines the millimeter width of the output file; PNG images are saved at actual pixel size. If you set a crop margin, the image will be cropped to the size of the TextBlock plus the specified margin. Margins are specified in millimeters (PDF, EPS, SVG) or pixels (PNG).

View code on GitHub

class Figure (n_rows: int = 1, n_cols: int = 1)

The Figure class is used to combine one or more images into a publication-ready figure. The general usage pattern is:

fig = eyekit.vis.Figure(1, 2)
fig.add_image(img1)
fig.add_image(img2)
fig.save('figure.pdf')

Initialized with:

n_rows Number of rows in the figure.
n_cols Number of columns in the figure.

View code on GitHub

Methods

def set_crop_margin(self, crop_margin): Set the crop margin of the embedded images. Each image in the figure will be cropped to the size and positioning of the most extreme text block extents, plus the specified margin. This has the effect of zooming in to all images in a consistent way – maintaining the aspect ratio and relative positioning of the text blocks across images. Margins are specified in figure millimeters.

View code on GitHub
def set_lettering(self, lettering=True, font_face=None, font_size=None): By default, each image caption is prefixed with a letter, (A), (B), (C), etc. If you want to turn this off, call Figure.set_lettering(False) prior to saving.

View code on GitHub
def set_padding(self, vertical=None, horizontal=None, edge=None): Set the vertical or horizontal padding between images or the padding around the edge of the figure. Padding is expressed in millimeters. By default, the vertical and horizontal padding between images is 4mm and the edge padding is 1mm.

View code on GitHub
def add_image(self, image, row=None, col=None): Add an Image to the figure. If a row and column index is specified, the image is placed in that position. Otherwise, image is placed in the next available position.

View code on GitHub
def save(self, output_path, width=150): Save the figure to some output_path. Figures can be saved as .pdf, .eps, or .svg. width determines the millimeter width of the output file.

View code on GitHub

class Booklet

The Booklet class is used to combine one or more figures into a multipage PDF booklet. The general usage pattern is:

booklet = eyekit.vis.Booklet()
booklet.add_figure(fig1)
booklet.add_figure(fig2)
booklet.save('booklet.pdf')

View code on GitHub

Methods

def add_figure(self, figure): Add a Figure to a new page in the booklet.

View code on GitHub
def save(self, output_path, width=210, height=297): Save the booklet to some output_path. Booklets can only be saved as .pdf. width and height determine the millimeter sizing of the booklet pages, which defaults to A4 (210x297mm).

View code on GitHub