Improve pdf usetex by adding support for font effects

jkseppan · jkseppan · commit 0f19207f1245 · 2008-12-31T13:20:50.000Z
svn path=/trunk/matplotlib/; revision=6718
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,3 +1,6 @@
+2008-12-31 Improve pdf usetex by adding support for font effects
+           (slanting and extending). - JKS
+
 2008-12-29 Fix a bug in pdf usetex support, which occurred if the same
            Type-1 font was used with different encodings, e.g. with
            Minion Pro and MnSymbol. - JKS
diff --git a/doc/api/dviread.rst b/doc/api/dviread.rst
@@ -0,0 +1,8 @@
+
+:mod:`matplotlib.dviread`
+=========================
+
+.. automodule:: matplotlib.dviread
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/api/index_backend_api.rst b/doc/api/index_backend_api.rst
@@ -8,3 +8,5 @@ matplotlib backends
    backend_gtkagg_api.rst
    backend_qt4agg_api.rst
    backend_wxagg_api.rst
+   dviread.rst
+   type1font.rst
diff --git a/doc/api/type1font.rst b/doc/api/type1font.rst
@@ -0,0 +1,8 @@
+
+:mod:`matplotlib.type1font`
+===========================
+
+.. automodule:: matplotlib.type1font
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/examples/pylab_examples/usetex_fonteffects.py b/examples/pylab_examples/usetex_fonteffects.py
@@ -0,0 +1,22 @@
+# This script demonstrates that font effects specified in your pdftex.map
+# are now supported in pdf usetex.
+
+import matplotlib
+matplotlib.rc('text', usetex=True)
+import pylab
+
+def setfont(font):
+    return r'\font\a %s at 14pt\a ' % font
+
+for y, font, text in zip(range(5),
+                         ['ptmr8r', 'ptmri8r', 'ptmro8r', 'ptmr8rn', 'ptmrr8re'],
+                         ['Nimbus Roman No9 L ' + x for x in
+                          ['', 'Italics (real italics for comparison)',
+                           '(slanted)', '(condensed)', '(extended)']]):
+    pylab.text(0, y, setfont(font) + text)
+
+pylab.ylim(-1, 5)
+pylab.xlim(-0.2, 0.6)
+pylab.setp(pylab.gca(), frame_on=False, xticks=(), yticks=())
+pylab.title('Usetex font effects')
+pylab.savefig('usetex_fonteffects.pdf')
diff --git a/lib/matplotlib/backends/backend_pdf.py b/lib/matplotlib/backends/backend_pdf.py
@@ -500,7 +500,7 @@ def writeFonts(self):
                 # from pdf.use14corefonts
                 fontdictObject = self._write_afm_font(filename)
             elif self.dviFontInfo.has_key(filename):
-                # a Type 1 font from a dvi file
+                # a Type 1 font from a dvi file; the filename is really the TeX name
                 fontdictObject = self.embedType1(filename, self.dviFontInfo[filename])
             else:
                 # a normal TrueType font
@@ -525,22 +525,25 @@ def _write_afm_font(self, filename):
         return fontdictObject
 
     def embedType1(self, texname, fontinfo):
-        # TODO: font effects such as SlantFont
         matplotlib.verbose.report(
-            'Embedding Type 1 font ' + fontinfo.fontfile +
-            ' with encoding ' + (fontinfo.encodingfile or '(none)'),
+            'Embedding ' + texname +
+            ' which is the Type 1 font ' + fontinfo.fontfile +
+            ' with encoding ' + (fontinfo.encodingfile or '(none)') +
+            ' and effects ' + `fontinfo.effects`,
             'debug')
 
-        # Use FT2Font to get several font properties
-        font = FT2Font(fontinfo.fontfile)
+        t1font = type1font.Type1Font(fontinfo.fontfile)
+        if fontinfo.effects:
+            t1font = t1font.transform(fontinfo.effects)
 
         # Font descriptors may be shared between differently encoded
         # Type-1 fonts, so only create a new descriptor if there is no
         # existing descriptor for this font.
-        fontdesc = self.type1Descriptors.get(fontinfo.fontfile)
+        effects = (fontinfo.effects.get('slant', 0.0), fontinfo.effects.get('extend', 1.0))
+        fontdesc = self.type1Descriptors.get((fontinfo.fontfile, effects))
         if fontdesc is None:
-            fontdesc = self.createType1Descriptor(font, fontinfo.fontfile)
-            self.type1Descriptors[fontinfo.fontfile] = fontdesc
+            fontdesc = self.createType1Descriptor(t1font, fontinfo.fontfile)
+            self.type1Descriptors[(fontinfo.fontfile, effects)] = fontdesc
 
         # Widths
         widthsObject = self.reserveObject('font widths')
@@ -551,7 +554,7 @@ def embedType1(self, texname, fontinfo):
         fontdict = {
             'Type':           Name('Font'),
             'Subtype':        Name('Type1'),
-            'BaseFont':       Name(font.postscript_name),
+            'BaseFont':       Name(t1font.prop['FontName']),
             'FirstChar':      0,
             'LastChar':       len(fontinfo.widths) - 1,
             'Widths':         widthsObject,
@@ -571,14 +574,14 @@ def embedType1(self, texname, fontinfo):
         self.writeObject(fontdictObject, fontdict)
         return fontdictObject
 
-    def createType1Descriptor(self, font, fontfile):
+    def createType1Descriptor(self, t1font, fontfile):
         # Create and write the font descriptor and the font file
         # of a Type-1 font
         fontdescObject = self.reserveObject('font descriptor')
         fontfileObject = self.reserveObject('font file')
 
-        _, _, fullname, familyname, weight, italic_angle, fixed_pitch, \
-            ul_position, ul_thickness = font.get_ps_font_info()
+        italic_angle = t1font.prop['ItalicAngle']
+        fixed_pitch = t1font.prop['isFixedPitch']
 
         flags = 0
         if fixed_pitch:   flags |= 1 << 0  # fixed width
@@ -590,26 +593,27 @@ def createType1Descriptor(self, font, fontfile):
         if 0:             flags |= 1 << 17 # TODO: small caps
         if 0:             flags |= 1 << 18 # TODO: force bold
 
+        ft2font = FT2Font(fontfile)
+        
         descriptor = {
             'Type':        Name('FontDescriptor'),
-            'FontName':    Name(font.postscript_name),
+            'FontName':    Name(t1font.prop['FontName']),
             'Flags':       flags,
-            'FontBBox':    font.bbox,
+            'FontBBox':    ft2font.bbox,
             'ItalicAngle': italic_angle,
-            'Ascent':      font.ascender,
-            'Descent':     font.descender,
+            'Ascent':      ft2font.ascender,
+            'Descent':     ft2font.descender,
             'CapHeight':   1000, # TODO: find this out
             'XHeight':     500, # TODO: this one too
             'FontFile':    fontfileObject,
-            'FontFamily':  familyname,
+            'FontFamily':  t1font.prop['FamilyName'],
             'StemV':       50, # TODO
             # (see also revision 3874; but not all TeX distros have AFM files!)
             #'FontWeight': a number where 400 = Regular, 700 = Bold
             }
 
         self.writeObject(fontdescObject, descriptor)
 
-        t1font = type1font.Type1Font(fontfile)
         self.beginStream(fontfileObject.id, None,
                          { 'Length1': len(t1font.parts[0]),
                            'Length2': len(t1font.parts[1]),
@@ -1369,14 +1373,14 @@ def draw_tex(self, gc, x, y, s, prop, angle):
                     self.file.dviFontInfo[dvifont.texname] = Bunch(
                         fontfile=psfont.filename,
                         encodingfile=psfont.encoding,
+                        effects=psfont.effects,
                         widths=dvifont.widths,
                         dvifont=dvifont)
-                    # TODO: font effects
                 seq += [['font', pdfname, dvifont.size]]
                 oldfont = dvifont
             seq += [['text', x1, y1, [chr(glyph)], x1+width]]
 
-        # Find consecutive text strings with constant x coordinate and
+        # Find consecutive text strings with constant y coordinate and
         # combine into a sequence of strings and kerns, or just one
         # string (if any kerns would be less than 0.1 points).
         i, curx = 0, 0
diff --git a/lib/matplotlib/dviread.py b/lib/matplotlib/dviread.py
@@ -1,12 +1,14 @@
 """
 An experimental module for reading dvi files output by TeX. Several
 limitations make this not (currently) useful as a general-purpose dvi
-preprocessor.
+preprocessor, but it is currently used by the pdf backend for
+processing usetex text.
 
 Interface::
 
   dvi = Dvi(filename, 72)
-  for page in dvi:          # iterate over pages
+  # iterate over pages (but only one page is supported for now):
+  for page in dvi:
       w, h, d = page.width, page.height, page.descent
       for x,y,font,glyph,width in page.text:
           fontname = font.texname
@@ -49,7 +51,7 @@ def __iter__(self):
         """
         Iterate through the pages of the file.
 
-        Returns (text, pages) pairs, where:
+        Returns (text, boxes) pairs, where:
           text is a list of (x, y, fontnum, glyphnum, width) tuples
           boxes is a list of (x, y, height, width) tuples
 
@@ -131,8 +133,8 @@ def _read(self):
 
     def _arg(self, nbytes, signed=False):
         """
-        Read and return an integer argument "nbytes" long.
-        Signedness is determined by the "signed" keyword.
+        Read and return an integer argument *nbytes* long.
+        Signedness is determined by the *signed* keyword.
         """
         str = self.file.read(nbytes)
         value = ord(str[0])
@@ -144,7 +146,7 @@ def _arg(self, nbytes, signed=False):
 
     def _dispatch(self, byte):
         """
-        Based on the opcode "byte", read the correct kinds of
+        Based on the opcode *byte*, read the correct kinds of
         arguments from the dvi file and call the method implementing
         that opcode with those arguments.
         """
@@ -385,9 +387,27 @@ class DviFont(object):
     Object that holds a font's texname and size, supports comparison,
     and knows the widths of glyphs in the same units as the AFM file.
     There are also internal attributes (for use by dviread.py) that
-    are _not_ used for comparison.
+    are *not* used for comparison.
 
     The size is in Adobe points (converted from TeX points).
+
+    .. attribute:: texname
+    
+       Name of the font as used internally by TeX and friends. This
+       is usually very different from any external font names, and
+       :class:`dviread.PsfontsMap` can be used to find the external
+       name of the font.
+
+    .. attribute:: size
+    
+       Size of the font in Adobe points, converted from the slightly
+       smaller TeX points.
+
+    .. attribute:: widths
+    
+       Widths of glyphs in glyph-space units, typically 1/1000ths of
+       the point size.
+    
     """
     __slots__ = ('texname', 'size', 'widths', '_scale', '_vf', '_tfm')
 
@@ -532,17 +552,27 @@ class Tfm(object):
     A TeX Font Metric file. This implementation covers only the bare
     minimum needed by the Dvi class.
 
-    Attributes:
+    .. attribute:: checksum
+
+       Used for verifying against the dvi file.
+
+    .. attribute:: design_size
 
-      checksum: for verifying against dvi file
+       Design size of the font (in what units?)
 
-      design_size: design size of the font (in what units?)
+    .. attribute::  width
 
-      width[i]: width of character \#i, needs to be scaled
-        by the factor specified in the dvi file
-        (this is a dict because indexing may not start from 0)
+       Width of each character, needs to be scaled by the factor
+       specified in the dvi file. This is a dict because indexing may
+       not start from 0.
 
-      height[i], depth[i]: height and depth of character \#i
+    .. attribute:: height
+
+       Height of each character.
+    
+    .. attribute:: depth
+        
+       Depth of each character.
     """
     __slots__ = ('checksum', 'design_size', 'width', 'height', 'depth')
 
@@ -581,7 +611,19 @@ def __init__(self, filename):
 class PsfontsMap(object):
     """
     A psfonts.map formatted file, mapping TeX fonts to PS fonts.
-    Usage: map = PsfontsMap('.../psfonts.map'); map['cmr10']
+    Usage::
+
+     >>> map = PsfontsMap(find_tex_file('pdftex.map'))
+     >>> entry = map['ptmbo8r']
+     >>> entry.texname
+     'ptmbo8r'
+     >>> entry.psname
+     'Times-Bold'
+     >>> entry.encoding
+     '/usr/local/texlive/2008/texmf-dist/fonts/enc/dvips/base/8r.enc'
+     >>> entry.effects
+     {'slant': 0.16700000000000001}
+     >>> entry.filename
 
     For historical reasons, TeX knows many Type-1 fonts by different
     names than the outside world. (For one thing, the names have to
@@ -594,11 +636,12 @@ class PsfontsMap(object):
     file names.
 
     A texmf tree typically includes mapping files called e.g.
-    psfonts.map, pdftex.map,  dvipdfm.map. psfonts.map is used by
+    psfonts.map, pdftex.map, dvipdfm.map. psfonts.map is used by
     dvips, pdftex.map by pdfTeX, and dvipdfm.map by dvipdfm.
-    psfonts.map might avoid embedding the 35 PostScript fonts, while
-    the pdf-related files perhaps only avoid the "Base 14" pdf fonts.
-    But the user may have configured these files differently.
+    psfonts.map might avoid embedding the 35 PostScript fonts (i.e.,
+    have no filename for them, as in the Times-Bold example above),
+    while the pdf-related files perhaps only avoid the "Base 14" pdf
+    fonts. But the user may have configured these files differently.
     """
     __slots__ = ('_font',)
 
@@ -655,10 +698,10 @@ def _register(self, words):
         subsetting, but I have no example of << in my TeX installation.
         """
         texname, psname = words[:2]
-        effects, encoding, filename = [], None, None
+        effects, encoding, filename = '', None, None
         for word in words[2:]:
             if not word.startswith('<'):
-                effects.append(word)
+                effects = word
             else:
                 word = word.lstrip('<')
                 if word.startswith('['):
@@ -670,6 +713,18 @@ def _register(self, words):
                 else:
                     assert filename is None
                     filename = word
+
+        eff = effects.split()
+        effects = {}
+        try:
+            effects['slant'] = float(eff[eff.index('SlantFont')-1])
+        except ValueError:
+            pass
+        try:
+            effects['extend'] = float(eff[eff.index('ExtendFont')-1])
+        except ValueError:
+            pass
+
         self._font[texname] = mpl_cbook.Bunch(
             texname=texname, psname=psname, effects=effects,
             encoding=encoding, filename=filename)
@@ -733,13 +788,18 @@ def _parse(self, file):
 
 def find_tex_file(filename, format=None):
     """
-    Call kpsewhich to find a file in the texmf tree.
-    If format is not None, it is used as the value for the --format option.
-    See the kpathsea documentation for more information.
+    Call :program:`kpsewhich` to find a file in the texmf tree. If
+    *format* is not None, it is used as the value for the
+    :option:`--format` option.
 
     Apparently most existing TeX distributions on Unix-like systems
     use kpathsea. I hear MikTeX (a popular distribution on Windows)
     doesn't use kpathsea, so what do we do? (TODO)
+
+    .. seealso::
+
+      `Kpathsea documentation <http://www.tug.org/kpathsea/>`_
+        The library that :program:`kpsewhich` is part of.
     """
 
     cmd = ['kpsewhich']
diff --git a/lib/matplotlib/type1font.py b/lib/matplotlib/type1font.py
