eyekit.text API documentation
Description: Defines the `TextBlock` and `InterestArea` objects for handling texts.

# Module `eyekit.text`

Defines the `TextBlock` and `InterestArea` objects for handling texts.

View code on GitHub

## Classes

`class Box`

  Representation of a bounding box, which provides an underlying framework for `Character`, `InterestArea`, and `TextBlock`.

  View code on GitHub

  ### Subclasses

  - Character
  - InterestArea
  - TextBlock

  ### Instance variables

  `var x : float`

    X-coordinate of the center of the bounding box

    View code on GitHub
  `var y : float`

    Y-coordinate of the center of the bounding box

    View code on GitHub
  `var x_tl : float`

    X-coordinate of the top-left corner of the bounding box

    View code on GitHub
  `var y_tl : float`

    Y-coordinate of the top-left corner of the bounding box

    View code on GitHub
  `var x_br : float`

    X-coordinate of the bottom-right corner of the bounding box

    View code on GitHub
  `var y_br : float`

    Y-coordinate of the bottom-right corner of the bounding box

    View code on GitHub
  `var width : float`

    Width of the bounding box

    View code on GitHub
  `var height : float`

    Height of the bounding box

    View code on GitHub
  `var box : tuple`

    The bounding box represented as x_tl, y_tl, width, and height

    View code on GitHub
  `var center : tuple`

    XY-coordinates of the center of the bounding box

    View code on GitHub
`class Character (char, x_tl, y_tl, x_br, y_br, baseline)`

  Representation of a single character of text. A `Character` object is essentially a one-letter string that occupies a position in space and has a bounding box. It is not usually necessary to create `Character` objects manually; they are created automatically during the instantiation of a `TextBlock`.

  View code on GitHub

  ### Ancestors

  - Box

  ### Instance variables

  `var baseline : float`

    The y position of the character baseline

    View code on GitHub

  ### Inherited members

  - `Box`:
    - `box`
    - `center`
    - `height`
    - `width`
    - `x`
    - `x_br`
    - `x_tl`
    - `y`
    - `y_br`
    - `y_tl`
`class InterestArea (chars, id, padding=0)`

  Representation of an interest area – a portion of a `TextBlock` object that is of potential interest. It is not usually necessary to create `InterestArea` objects manually; they are created automatically when you slice a `TextBlock` object or when you iterate over lines, words, characters, ngrams, or zones parsed from the raw text.

  View code on GitHub

  ### Ancestors

  - Box

  ### Instance variables

  `var id : str`

    Interest area ID. By default, these ID's have the form 1:5:10, which represents the line number and column indices of the `InterestArea` in its parent `TextBlock`. However, IDs can also be changed to any arbitrary string.

    View code on GitHub
  `var baseline : float`

    The y position of the text baseline

    View code on GitHub
  `var text : str`

    String representation of the interest area

    View code on GitHub

  ### Inherited members

  - `Box`:
    - `box`
    - `center`
    - `height`
    - `width`
    - `x`
    - `x_br`
    - `x_tl`
    - `y`
    - `y_br`
    - `y_tl`
`class TextBlock (text: list, position: tuple = None, font_face: str = None, font_size: float = None, line_height: float = None, alphabet: str = None)`

  Representation of a piece of text, which may be a word, sentence, or entire multiline passage.

  Initialized with:

  - `text` The line of text (string) or lines of text (list of strings). Optionally, these can be marked up with arbitrary interest areas (zones); for example, `The quick brown fox jump[ed]{past-suffix} over the lazy dog`.

  - `position` XY-coordinates of the left edge of the first baseline of the block of text.

  - `font_face` Name of a font available on your system. The keywords `italic` and/or `bold` can also be included to select the desired style, e.g., `Minion Pro bold italic`.

  - `font_size` Font size in points (at 72dpi). To convert a font size from some other dpi, use `font_size_at_72dpi()`.

  - `line_height` Height of a line of text in points. Generally speaking, for single line spacing, the line height is equal to the font size, for double line spacing, the line height is equal to 2 × the font size, etc. By default, the line height is assumed to be the same as the font size (single line spacing). This parameter also effectively determines the height of the bounding boxes around interest areas.

  - `alphabet` A string of characters that are to be considered alphabetical, which determines, for example, what is considered a word. By default, Eyekit considers the standard Latin, Greek, and Cyrillic alphabets to be alphabetical, plus the special and accented characters from most European languages. However, if you need support for some other alphabet, or if you want to modify Eyekit's default behavior, you can set an alternative alphabet here. This parameter is case sensitive, so you must supply upper- and lower-case variants. For example, if you wanted to treat apostrophes and hyphens as alphabetical, you might use `alphabet="A-Za-z'-"`. This would allow, for example, "Where's the orang-utan?" to be treated as three words rather than five.

  View code on GitHub

  ### Ancestors

  - Box

  ### Static methods

  `def defaults(position: tuple = None, font_face: str = None, font_size: float = None, line_height: float = None, alphabet: str = None)`

    Set default `TextBlock` parameters. If you plan to create several `TextBlock`s with the same parameters, it may be useful to set the default parameters at the top of your script or at the start of your session:

        import eyekit
        eyekit.TextBlock.defaults(font_face='Helvetica')
        txt = eyekit.TextBlock('The quick brown fox')
        print(txt.font_face) # 'Helvetica'

    View code on GitHub

  ### Instance variables

  `var text : str`

    String representation of the text

    View code on GitHub
  `var position : tuple`

    Position of the `TextBlock`

    View code on GitHub
  `var font_face : str`

    Name of the font

    View code on GitHub
  `var font_size : float`

    Font size in points

    View code on GitHub
  `var line_height : float`

    Line height in points

    View code on GitHub
  `var alphabet : str`

    Characters that are considered alphabetical

    View code on GitHub
  `var n_rows : int`

    Number of rows in the text (i.e. the number of lines)

    View code on GitHub
  `var n_cols : int`

    Number of columns in the text (i.e. the number of characters in the widest line)

    View code on GitHub
  `var line_positions : list`

    Y-coordinates of the center of each line of text

    View code on GitHub
  `var word_centers : list`

    XY-coordinates of the center of each word

    View code on GitHub

  ### Methods

  `def zones(self)`

    Iterate over each marked up zone as an `InterestArea`.

    View code on GitHub
  `def which_zone(self, fixation)`

    Return the marked-up zone that the fixation falls inside as an `InterestArea`.

    View code on GitHub
  `def lines(self)`

    Iterate over each line as an `InterestArea`.

    View code on GitHub
  `def which_line(self, fixation)`

    Return the line that the fixation falls inside as an `InterestArea`.

    View code on GitHub
  `def words(self, pattern=None, line_n=None, add_padding=True)`

    Iterate over each word as an `InterestArea`. Optionally, you can supply a regex pattern to define what constitutes a word or to pick out specific words. For example, `r'\b[Tt]he\b'` gives you all occurrences of the word the or `'[a-z]+ing'` gives you all words ending with -ing. `add_padding` adds half of the width of a space character to the left and right edges of the word's bounding box, so that fixations that fall on a space between two words will at least fall into one of the two words' bounding boxes.

    View code on GitHub
  `def which_word(self, fixation, pattern=None, line_n=None, add_padding=True)`

    Return the word that the fixation falls inside as an `InterestArea`. For the meaning of `pattern` and `add_padding` see `TextBlock.words()`.

    View code on GitHub
  `def characters(self, line_n=None, alphabetical_only=True)`

    Iterate over each character as an `InterestArea`.

    View code on GitHub
  `def which_character(self, fixation, line_n=None, alphabetical_only=True)`

    Return the character that the fixation falls inside as an `InterestArea`.

    View code on GitHub
  `def ngrams(self, n, line_n=None, alphabetical_only=True)`

    Iterate over each ngram, for given n, as an `InterestArea`.

    View code on GitHub

  ### Inherited members

  - `Box`:
    - `box`
    - `center`
    - `height`
    - `width`
    - `x`
    - `x_br`
    - `x_tl`
    - `y`
    - `y_br`
    - `y_tl`