# tables: Access TrueType/OpenType tables

## Overview

This folder is a subpackage of `fontTools.ttLib`. Each module here is a specialized TrueType/OpenType table converter: they can convert raw data to Python objects and vice versa. Usually you do not need to use these modules directly: they are imported and used automatically when needed by `fontTools.ttLib`.

In addition to the tables defined in the official TrueType/OpenType specification documents, several specialty tables are supported that are used by specific vendors (including the Graphite shaping engine and Apple’s AAT). Note that fontTools supports the tables that provide the core functionality of AAT, but does not guarantee everything.

Similarly, fontTools supports some third-party tables used by external applications (such as FontForge and Microsoft’s VTT), but may not support every private table employed by those applications.

## Accessing tables

The Python modules representing the tables have pretty strange names: this is due to the fact that we need to map TT/OT table tags (which are case sensitive) to filenames (which on macOS and Windows are not case sensitive) as well as to Python identifiers. The latter means that each table identifier can only contain `[A-Za-z0-9_]` and cannot start with a number.

The convention adopted is that capital letters in a table tag are transformed into the letter followed by an underscore (e.g., `A_`), while lowercase letters and numbers are preceded by an underscore (e.g., `_a`).

`fontTools.ttLib` provides functions to expand a tag into the format used here:

    >>> from fontTools import ttLib
    >>> ttLib.tagToIdentifier("FOO ")
    'F_O_O_'
    >>> ttLib.tagToIdentifier("cvt ")
    '_c_v_t'
    >>> ttLib.tagToIdentifier("OS/2")
    'O_S_2f_2'
    >>> ttLib.tagToIdentifier("glyf")
    '_g_l_y_f'
    >>>

And vice versa:

    >>> ttLib.identifierToTag("F_O_O_")
    'FOO '
    >>> ttLib.identifierToTag("_c_v_t")
    'cvt '
    >>> ttLib.identifierToTag("O_S_2f_2")
    'OS/2'
    >>> ttLib.identifierToTag("_g_l_y_f")
    'glyf'
    >>>

Eg. the ‘glyf’ table converter lives in a Python file called:

    _g_l_y_f.py

The converter itself is a class, named `table_` + expandedtag. Eg:

    class table__g_l_y_f:
            etc.

Note that if you _do_ need to use such modules or classes manually, there are two convenient API functions that let you find them by tag:

    >>> ttLib.getTableModule('glyf')
    <module 'ttLib.tables._g_l_y_f'>
    >>> ttLib.getTableClass('glyf')
    <class ttLib.tables._g_l_y_f.table__g_l_y_f at 645f400>
    >>

## Helper modules

In addition to the core table-conversion implementations, a set of helper and utility modules is also found in this package. You should not normally need to access these modules directly, but consulting them might be valuable if you need to add fontTools support for a new table type.

In that case, a good place to start is with the documentation for the base table classes:

- Base table classes and API

The modules that provide lower-level helper functionality include implementations of common OpenType data structures, support for OpenType font variations, and various classes needed for tables containing bitmap data or for tables used by the Graphite engine:

- OpenType-table helper modules
- OpenType variations helper module
- Bitmap-data helper modules
- Graphite table helper module

A module is also included for assembling and disassembling TrueType bytecode:

- ttProgram: TrueType bytecode assembler/disassembler

## Tables currently supported

- `ankr`: Anchor Point table
- `avar`: Axis Variations table
- `BASE`: Baseline table
- `bsln`: Baseline
- `CBDT`: Color Bitmap Data table
- `CBLC`: Color Bitmap Location table
- `CFF`: Compact Font Format table
- `CFF2`: Compact Font Format (CFF) Version 2 table
- `cidg`: CID to Glyph ID table
- `cmap`: Character to Glyph Index Mapping table
- `COLR`: Color table
- `CPAL`: Color Palette table
- `cvar`: CVT Variations table
- `cvt`: Control Value Table
- `DSIG`: Digital Signature table
- `EBDT`: Embedded Bitmap Data table
- `EBLC`: Embedded Bitmap Location table
- `Feat`: Graphite Feature table
- `feat`: Feature name table
- `FFTM`: FontForge Time Stamp table
- `fpgm`: Font Program table
- `fvar`: Font Variations table
- `gasp`: Grid-fitting and Scan-conversion Procedure table
- `gcid`: Glyph ID to CID table
- `GDEF`: Glyph Definition table
- `Glat`: Graphite Glyph Attributes table
- `Gloc`: Graphite index to glyph attributes table
- `glyf`: Glyph Data table
- `GPOS`: Glyph Positioning table
- `GSUB`: Glyph Substitution table
- `gvar`: Glyph Variations table
- `hdmx`: Horizontal Device Metrics table
- `head`: Font Header table
- `hhea`: Horizontal Header table
- `hmtx`: Horizontal Metrics table
- `HVAR`: Horizontal Metrics Variations table
- `JSTF`: Justification table
- `kern`: Kerning table
- `lcar`: Ligature Caret Table
- `loca`: Index to Location table
- `ltag`: Language Tag table
- `LTSH`: Linear Threshold table
- `MATH`: Mathematical Typesetting table
- `maxp`: Maximum Profile table
- `meta`: Metadata table
- `mort`: Glyph Metamorphosis Table
- `morx`: Extended Glyph Metamorphosis Table
- `MVAR`: Metrics Variations table
- `name`: Naming table
- `opbd`: Optical Bounds Table
- `OS/2`: OS/2 and Windows Metrics table
- `post`: PostScript table
- `prep`: Control Value Program table
- `prop`: Glyph Properties Table
- `sbix`: Standard Bitmap Graphics table
- `Silf`: Graphite Rules table
- `Sill`: Graphite Languages table
- `STAT`: Style Attributes table
- `SVG`: SVG (Scalable Vector Graphics) table
- `trak`: Tracking table
- `TTFA`: ttfautohint Parameter table
- `VDMX`: Vertical Device Metrics table
- `vhea`: Vertical Header table
- `vmtx`: Vertical Metrics table
- `VORG`: Vertical Origin table
- `VTT*` Visual TrueType private tables
- `VVAR`: Vertical Metrics Variations table