eyekit.vis API documentation
Description: Defines the `Image`, `Figure`, and `Booklet` objects, which are used to create visualizations.

# Module `eyekit.vis`

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

View code on GitHub

## 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)`

    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.

    View code on GitHub
  `def draw_sequence_comparison(self, reference_sequence, fixation_sequence, color_match='black', color_mismatch='red')`

    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