diff --git a/PIL/ImageFont.py b/PIL/ImageFont.py index 826b37d5c..8313ee3ba 100644 --- a/PIL/ImageFont.py +++ b/PIL/ImageFont.py @@ -61,21 +61,6 @@ except ImportError: # position according to dx, dy. # -------------------------------------------------------------------- -## -# The ImageFont module defines a class with the same name. -# Instances of this class store bitmap fonts, and are used with the -# text method of the ImageDraw class. -#

-# PIL uses it's own font file format to store bitmap fonts. You can -# use the pilfont utility to convert BDF and PCF font -# descriptors (X window font formats) to this format. -#

-# Starting with version 1.1.4, PIL can be configured to support -# TrueType and OpenType fonts. For earlier version, TrueType -# support is only available as part of the imToolkit package -# -# @see ImageDraw#ImageDraw.text -# @see pilfont class ImageFont: "PIL font wrapper" @@ -197,41 +182,42 @@ class TransposedFont: return im.transpose(self.orientation) return im -## -# Load font file. This function loads a font object from the given -# bitmap font file, and returns the corresponding font object. -# -# @param filename Name of font file. -# @return A font object. -# @exception IOError If the file could not be read. def load(filename): - "Load a font file." + """ + Load a font file. This function loads a font object from the given + bitmap font file, and returns the corresponding font object. + + :param filename: Name of font file. + :return: A font object. + :exception IOError: If the file could not be read. + """ f = ImageFont() f._load_pilfont(filename) return f -## -# Load a TrueType or OpenType font file, and create a font object. -# This function loads a font object from the given file, and creates -# a font object for a font of the given size. -#

-# This function requires the _imagingft service. -# -# @param filename A truetype font file. Under Windows, if the file -# is not found in this filename, the loader also looks in Windows -# fonts directory -# @param size The requested size, in points. -# @param index Which font face to load (default is first available face). -# @param encoding Which font encoding to use (default is Unicode). Common -# encodings are "unic" (Unicode), "symb" (Microsoft Symbol), "ADOB" -# (Adobe Standard), "ADBE" (Adobe Expert), and "armn" (Apple Roman). -# See the FreeType documentation for more information. -# @return A font object. -# @exception IOError If the file could not be read. def truetype(font=None, size=10, index=0, encoding="", filename=None): - "Load a truetype font file." + """ + Load a TrueType or OpenType font file, and create a font object. + This function loads a font object from the given file, and creates + a font object for a font of the given size. + + This function requires the _imagingft service. + + :param filename: A truetype font file. Under Windows, if the file + is not found in this filename, the loader also looks in + Windows :file:`fonts/` directory. + :param size: The requested size, in points. + :param index: Which font face to load (default is first available face). + :param encoding: Which font encoding to use (default is Unicode). Common + encodings are "unic" (Unicode), "symb" (Microsoft + Symbol), "ADOB" (Adobe Standard), "ADBE" (Adobe Expert), + and "armn" (Apple Roman). See the FreeType documentation + for more information. + :return: A font object. + :exception IOError: If the file could not be read. + """ if filename: if warnings: @@ -251,17 +237,16 @@ def truetype(font=None, size=10, index=0, encoding="", filename=None): return FreeTypeFont(filename, size, index, encoding) raise -## -# Load font file. Same as load, but searches for a bitmap font along -# the Python path. -# -# @param filename Name of font file. -# @return A font object. -# @exception IOError If the file could not be read. -# @see #load def load_path(filename): - "Load a font file, searching along the Python path." + """ + Load font file. Same as :py:func:`~PIL.ImageFont.load`, but searches for a + bitmap font along the Python path. + + :param filename: Name of font file. + :return: A font object. + :exception IOError: If the file could not be read. + """ for dir in sys.path: if isDirectory(dir): if not isinstance(filename, str): @@ -275,13 +260,14 @@ def load_path(filename): pass raise IOError("cannot find font file") -## -# Load a (probably rather ugly) default font. -# -# @return A font object. def load_default(): - "Load a default font." + """Load a "better than nothing" default font. + + .. versionadded:: 1.1.4 + + :return: A font object. + """ from io import BytesIO import base64 f = ImageFont() @@ -406,6 +392,7 @@ w7IkEbzhVQAAAABJRU5ErkJggg== ''')))) return f + if __name__ == "__main__": # create font data chunk for embedding import base64, os, sys diff --git a/docs/reference/ImageEnhance.rst b/docs/reference/ImageEnhance.rst index db068bb84..e951b8e53 100644 --- a/docs/reference/ImageEnhance.rst +++ b/docs/reference/ImageEnhance.rst @@ -7,11 +7,8 @@ The :py:mod:`ImageEnhance` module contains a number of classes that can be used for image enhancement. -Example -------- - -Vary the Sharpness of an Image -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Example: Vary the sharpness of an image +--------------------------------------- .. code-block:: python diff --git a/docs/reference/ImageFilter.rst b/docs/reference/ImageFilter.rst index 0a4f29bfa..9866792ff 100644 --- a/docs/reference/ImageFilter.rst +++ b/docs/reference/ImageFilter.rst @@ -5,15 +5,15 @@ ========================= The :py:mod:`ImageFilter` module contains definitions for a pre-defined set of -filters, which can be be used with :py:meth:`Image.filter() -`. +filters, which can be be used with the :py:meth:`Image.filter() +` method. -Example Filter an image ------------------------ +Example: Filter an image +------------------------ .. code-block:: python - import ImageFilter + from PIL import ImageFilter im1 = im.filter(ImageFilter.BLUR) diff --git a/docs/reference/ImageFont.rst b/docs/reference/ImageFont.rst new file mode 100644 index 000000000..c93df7d3b --- /dev/null +++ b/docs/reference/ImageFont.rst @@ -0,0 +1,69 @@ +.. py:module:: PIL.ImageFont +.. py:currentmodule:: PIL.ImageFont + +:mod:`ImageFont` Module +======================= + +The :py:mod:`ImageFont` module defines a class with the same name. Instances of +this class store bitmap fonts, and are used with the +:py:meth:`PIL.ImageDraw.Draw.text` method. + +PIL uses its own font file format to store bitmap fonts. You can use the +:command`pilfont` utility to convert BDF and PCF font descriptors (X window +font formats) to this format. + +Starting with version 1.1.4, PIL can be configured to support TrueType and +OpenType fonts (as well as other font formats supported by the FreeType +library). For earlier versions, TrueType support is only available as part of +the imToolkit package + +Example +------- + +.. code-block:: python + + from PIL import ImageFont, ImageDraw + + draw = ImageDraw.Draw(image) + + # use a bitmap font + font = ImageFont.load("arial.pil") + + draw.text((10, 10), "hello", font=font) + + # use a truetype font + font = ImageFont.truetype("arial.ttf", 15) + + draw.text((10, 25), "world", font=font) + +Functions +--------- + +.. autofunction:: PIL.ImageFont.load +.. autofunction:: PIL.ImageFont.load_path +.. autofunction:: PIL.ImageFont.truetype +.. autofunction:: PIL.ImageFont.load_default + +Methods +------- + +.. py:method:: PIL.ImageFont.ImageFont.getsize(text) + + :return: (width, height) + +.. py:method:: PIL.ImageFont.ImageFont.getmask(text, mode='') + + Create a bitmap for the text. + + If the font uses antialiasing, the bitmap should have mode “L” and use a + maximum value of 255. Otherwise, it should have mode “1”. + + :param text: Text to render. + :param mode: Used by some graphics drivers to indicate what mode the + driver prefers; if empty, the renderer may return either + mode. Note that the mode is always a string, to simplify + C-level implementations. + + .. versionadded:: 1.1.5 + :return: An internal PIL storage memory instance as defined by the + :py:mod:`PIL.Image.core` interface module. diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 510970303..5f8d6fac3 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -11,4 +11,5 @@ Reference ImageEnhance ImageFile ImageFilter + ImageFont ../PIL