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: str = None, font_size: Union[int, float] = 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, per-figure, or per-annotation 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: str, *, font_face: str = None, font_size: Union[int, float] = None)`

    Set the image's caption, which will be shown above the image if you place it inside a `Figure`. If no font is set, the default font will be used (see `set_default_font()`).

    View code on GitHub
  `def set_background_color(self, color: Union[str, tuple])`

    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 set_background_image(self, file_path)`

    Set a background image. The background image must be a PNG file that matches the dimensions of the `Image` object. Note also that the resulting `Image` object must be saved as a PNG (a background image cannot be combined with vector output).

    View code on GitHub
  `def set_crop_area(self, rect)`

    Crop the final image to a particular rectangular area of the screen. `rect` should be a tuple of the form `(x, y, width, height)` specifying the crop area (in screen coordinates) or a Box-like object, such as a TextBlock or InterestArea. If no crop area is set, then it defaults to the maximum extents of all TextBlocks drawn to the Image.

    View code on GitHub
  `def draw_text_block(self, text_block, *, color: Union[str, tuple] = None, mask_text: bool = False)`

    Draw a `TextBlock` on the image. `color` defaults to black if unspecified. If `mask_text` is set to `True`, the text will be displayed as a series of rectangles, which is useful if you want to deemphasize the linguistic content.

    View code on GitHub
  `def draw_fixation_sequence(self, fixation_sequence, *, show_saccades: bool = True, show_discards: bool = False, color: Union[str, tuple, ] = 'black', discard_color: Union[str, tuple] = 'gray', saccade_color: Union[str, tuple] = None, number_fixations: bool = False, fixation_radius: Union[int, float, ] = None, stroke_width: Union[int, float] = 0.5, opacity: float = 1.0)`

    Draw a `FixationSequence` on the image. Optionally, you can choose whether or not to display saccade lines and discarded fixations. `color`, `discard_color`, and `saccade_color` determine the colors of fixations, discarded fixations, and saccade lines respectively. If `number_fixations` is `True`, each fixation is superimposed with its index. By default, the radius of each fixation is calculated as `sqrt(duration/pi)`, such that the area of each fixation will correspond to duration. If `fixation_radius` is set to a number, all fixations will be rendered at a constant size. `stroke_width` controls the thickness of saccade lines. `opacity` controls the opacity of fixations. If you want to set the `color` or `fixation_radius` of each fixation independently, pass in a function that takes a fixation and returns a color. For example, to color code fixations that have the tag `special_fixation` you could use a lambda function such as

        color = lambda fxn: 'red' if fxn.has_tag('special_fixation') else 'black'

    or to base the fixation size on pupil size, you could use:

        fixation_radius = lambda fxn: (fxn.pupil_size / 3.14159) ** 0.5

    View code on GitHub
  `def draw_heatmap(self, text_block, distribution, *, color: Union[str, tuple] = '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_line(self, start_xy: tuple, end_xy: tuple, *, color: Union[str, tuple] = 'black', stroke_width: Union[int, float] = 1, dashed: Union[bool, tuple] = False, opacity: float = 1.0)`

    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. If `dashed` is `True`, the line will have a dashed style (or a custom dash pattern can be supplied, e.g. `dashed=(1,2,4,2)`).

    View code on GitHub
  `def draw_circle(self, xy: tuple, radius: Union[int, float], *, color: Union[str, tuple] = None, stroke_width: Union[int, float] = 1, dashed: Union[bool, tuple] = False, fill_color: Union[str, tuple] = None, opacity: float = 1.0)`

    Draw an arbitrary circle on the image centered at `xy` with some `radius`. `stroke_width` is set in points for vector output or pixels for PNG output. If `dashed` is `True`, the line will have a dashed style (or a custom dash pattern can be supplied, e.g. `dashed=(1,2,4,2)`). If no `color` or `fill_color` is provided, `color` will default to black. `opacity` controls the opacity of the circle's fill color and should be set between 0 (fully transparent) and 1 (fully opaque).

    View code on GitHub
  `def draw_rectangle(self, rect, *, color: Union[str, tuple] = None, stroke_width: Union[int, float] = 1, dashed: Union[bool, tuple] = False, fill_color: Union[str, tuple] = None, opacity: float = 1.0)`

    Draw a rectangle on the image. You can pass in some Box-like object, such as an `InterestArea`, or you can pass a tuple of the form (x, y, width, height). `stroke_width` is set in points for vector output or pixels for PNG output. If `dashed` is `True`, the line will have a dashed style (or a custom dash pattern can be supplied, e.g. `dashed=(1,2,4,2)`). If no `color` or `fill_color` is provided, `color` will default to black. `opacity` controls the opacity of the rectangle's fill color and should be set between 0 (fully transparent) and 1 (fully opaque).

    View code on GitHub
  `def draw_annotation(self, xy: tuple, text: str, *, font_face: str = None, font_size: Union[int, float] = None, color: Union[str, tuple] = 'black', anchor: str = 'left')`

    Draw arbitrary text on the image located at `xy`. If no font is set, the default font will be used (see `set_default_font()`). `font_size` is set in points for vector output or pixels for PNG output. `anchor` controls how the text is aligned relative to `xy` and may be set to `left`, `center`, or `right`.

    View code on GitHub
  `def save(self, output_path, *, width: int = 150, crop_margin: int = 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). EPS does not support opacity effects.

    View code on GitHub
  `def render_frame(self)`

    Render the image to PNG and return the bytestream. This can be used to build videos and animations.

    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: int)`

    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_border_style(self, *, stroke_width: Union[int, float] = None, color: Union[str, tuple] = None)`

    Set the thickness and color of the image borders. By default, image border are 1pt black.

    View code on GitHub
  `def set_enumeration(self, style: str = None, *, font_face: str = None, font_size: Union[int, float] = None)`

    By default, each image caption is prefixed with a letter in parentheses: (A), (B), (C), etc. If you want to turn this off, call `Figure.set_enumeration(False)` prior to saving. You can also specify a custom style using the `<A>`, `<a>`, or `<1>` tags; for example `Figure.set_enumeration('[<1>]')` will result in [1], [2], [3] etc. If no font is set, the default font will be used (see `set_default_font()`).

    View code on GitHub
  `def set_padding(self, *, vertical: int = None, horizontal: int = None, edge: int = 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: Image, *, row: int = None, col: int = 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: int = 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. EPS does not support opacity effects.

    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: Figure)`

    Add a `Figure` to a new page in the booklet.

    View code on GitHub
  `def save(self, output_path, *, width: int = 210, height: int = 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