mirror of
https://github.com/python-pillow/Pillow.git
synced 2025-07-11 00:32:27 +03:00
improve ImageShow docs
This commit is contained in:
parent
41a75210b5
commit
4a9afc79bf
|
@ -62,14 +62,6 @@ can be found here.
|
||||||
:undoc-members:
|
:undoc-members:
|
||||||
:show-inheritance:
|
:show-inheritance:
|
||||||
|
|
||||||
:mod:`ImageShow` Module
|
|
||||||
-----------------------
|
|
||||||
|
|
||||||
.. automodule:: PIL.ImageShow
|
|
||||||
:members:
|
|
||||||
:undoc-members:
|
|
||||||
:show-inheritance:
|
|
||||||
|
|
||||||
:mod:`ImageTransform` Module
|
:mod:`ImageTransform` Module
|
||||||
----------------------------
|
----------------------------
|
||||||
|
|
||||||
|
|
27
docs/reference/ImageShow.rst
Normal file
27
docs/reference/ImageShow.rst
Normal file
|
@ -0,0 +1,27 @@
|
||||||
|
.. py:module:: PIL.ImageShow
|
||||||
|
.. py:currentmodule:: PIL.ImageShow
|
||||||
|
|
||||||
|
:py:mod:`ImageShow` Module
|
||||||
|
==========================
|
||||||
|
|
||||||
|
The :py:mod:`ImageShow` Module is used to display images.
|
||||||
|
All default viewers convert the image to be shown to PNG format.
|
||||||
|
|
||||||
|
.. autofunction:: PIL.ImageShow.show
|
||||||
|
|
||||||
|
.. autoclass:: WindowsViewer
|
||||||
|
.. autoclass:: MacViewer
|
||||||
|
|
||||||
|
.. class:: UnixViewer
|
||||||
|
|
||||||
|
The following viewers may be registered on Unix-based systems, if the given command is found:
|
||||||
|
|
||||||
|
.. autoclass:: PIL.ImageShow.DisplayViewer
|
||||||
|
.. autoclass:: PIL.ImageShow.EogViewer
|
||||||
|
.. autoclass:: PIL.ImageShow.XVViewer
|
||||||
|
|
||||||
|
.. autofunction:: PIL.ImageShow.register
|
||||||
|
.. autoclass:: PIL.ImageShow.Viewer
|
||||||
|
:member-order: bysource
|
||||||
|
:members:
|
||||||
|
:undoc-members:
|
|
@ -22,6 +22,7 @@ Reference
|
||||||
ImagePath
|
ImagePath
|
||||||
ImageQt
|
ImageQt
|
||||||
ImageSequence
|
ImageSequence
|
||||||
|
ImageShow
|
||||||
ImageStat
|
ImageStat
|
||||||
ImageTk
|
ImageTk
|
||||||
ImageWin
|
ImageWin
|
||||||
|
|
|
@ -24,6 +24,14 @@ _viewers = []
|
||||||
|
|
||||||
|
|
||||||
def register(viewer, order=1):
|
def register(viewer, order=1):
|
||||||
|
"""
|
||||||
|
The :py:func:`register` function is used to register additional viewers.
|
||||||
|
|
||||||
|
:param viewer: The viewer to be registered.
|
||||||
|
:param order:
|
||||||
|
A negative integer to prepend this viewer to the list,
|
||||||
|
or a positive integer to append it.
|
||||||
|
"""
|
||||||
try:
|
try:
|
||||||
if issubclass(viewer, Viewer):
|
if issubclass(viewer, Viewer):
|
||||||
viewer = viewer()
|
viewer = viewer()
|
||||||
|
@ -42,7 +50,7 @@ def show(image, title=None, **options):
|
||||||
:param image: An image object.
|
:param image: An image object.
|
||||||
:param title: Optional title. Not all viewers can display the title.
|
:param title: Optional title. Not all viewers can display the title.
|
||||||
:param \**options: Additional viewer options.
|
:param \**options: Additional viewer options.
|
||||||
:returns: True if a suitable viewer was found, false otherwise.
|
:returns: ``True`` if a suitable viewer was found, ``False`` otherwise.
|
||||||
"""
|
"""
|
||||||
for viewer in _viewers:
|
for viewer in _viewers:
|
||||||
if viewer.show(image, title=title, **options):
|
if viewer.show(image, title=title, **options):
|
||||||
|
@ -56,6 +64,10 @@ class Viewer:
|
||||||
# main api
|
# main api
|
||||||
|
|
||||||
def show(self, image, **options):
|
def show(self, image, **options):
|
||||||
|
"""
|
||||||
|
The main function for displaying an image.
|
||||||
|
Converts the given image to the target format and displays it.
|
||||||
|
"""
|
||||||
|
|
||||||
# save temporary image to disk
|
# save temporary image to disk
|
||||||
if not (
|
if not (
|
||||||
|
@ -70,25 +82,31 @@ class Viewer:
|
||||||
# hook methods
|
# hook methods
|
||||||
|
|
||||||
format = None
|
format = None
|
||||||
|
"""The format to convert the image into."""
|
||||||
options = {}
|
options = {}
|
||||||
|
"""Additional options used to convert the image."""
|
||||||
|
|
||||||
def get_format(self, image):
|
def get_format(self, image):
|
||||||
"""Return format name, or None to save as PGM/PPM"""
|
"""Return format name, or ``None`` to save as PGM/PPM."""
|
||||||
return self.format
|
return self.format
|
||||||
|
|
||||||
def get_command(self, file, **options):
|
def get_command(self, file, **options):
|
||||||
|
"""
|
||||||
|
Returns the command used to display the file.
|
||||||
|
Not implemented in the base class.
|
||||||
|
"""
|
||||||
raise NotImplementedError
|
raise NotImplementedError
|
||||||
|
|
||||||
def save_image(self, image):
|
def save_image(self, image):
|
||||||
"""Save to temporary file, and return filename"""
|
"""Save to temporary file and return filename."""
|
||||||
return image._dump(format=self.get_format(image), **self.options)
|
return image._dump(format=self.get_format(image), **self.options)
|
||||||
|
|
||||||
def show_image(self, image, **options):
|
def show_image(self, image, **options):
|
||||||
"""Display given image"""
|
"""Display the given image."""
|
||||||
return self.show_file(self.save_image(image), **options)
|
return self.show_file(self.save_image(image), **options)
|
||||||
|
|
||||||
def show_file(self, file, **options):
|
def show_file(self, file, **options):
|
||||||
"""Display given file"""
|
"""Display the given file."""
|
||||||
os.system(self.get_command(file, **options))
|
os.system(self.get_command(file, **options))
|
||||||
return 1
|
return 1
|
||||||
|
|
||||||
|
@ -96,9 +114,9 @@ class Viewer:
|
||||||
# --------------------------------------------------------------------
|
# --------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
if sys.platform == "win32":
|
|
||||||
|
|
||||||
class WindowsViewer(Viewer):
|
class WindowsViewer(Viewer):
|
||||||
|
"""The default viewer on Windows is the default system application for PNG files."""
|
||||||
|
|
||||||
format = "PNG"
|
format = "PNG"
|
||||||
options = {"compress_level": 1}
|
options = {"compress_level": 1}
|
||||||
|
|
||||||
|
@ -109,11 +127,14 @@ if sys.platform == "win32":
|
||||||
'&& del /f "%s"' % (file, file)
|
'&& del /f "%s"' % (file, file)
|
||||||
)
|
)
|
||||||
|
|
||||||
|
|
||||||
|
if sys.platform == "win32":
|
||||||
register(WindowsViewer)
|
register(WindowsViewer)
|
||||||
|
|
||||||
elif sys.platform == "darwin":
|
|
||||||
|
|
||||||
class MacViewer(Viewer):
|
class MacViewer(Viewer):
|
||||||
|
"""The default viewer on MacOS using ``Preview.app``."""
|
||||||
|
|
||||||
format = "PNG"
|
format = "PNG"
|
||||||
options = {"compress_level": 1}
|
options = {"compress_level": 1}
|
||||||
|
|
||||||
|
@ -140,11 +161,10 @@ elif sys.platform == "darwin":
|
||||||
os.remove(path)
|
os.remove(path)
|
||||||
return 1
|
return 1
|
||||||
|
|
||||||
|
|
||||||
|
if sys.platform == "darwin":
|
||||||
register(MacViewer)
|
register(MacViewer)
|
||||||
|
|
||||||
else:
|
|
||||||
|
|
||||||
# unixoids
|
|
||||||
|
|
||||||
class UnixViewer(Viewer):
|
class UnixViewer(Viewer):
|
||||||
format = "PNG"
|
format = "PNG"
|
||||||
|
@ -167,25 +187,29 @@ else:
|
||||||
os.remove(path)
|
os.remove(path)
|
||||||
return 1
|
return 1
|
||||||
|
|
||||||
# implementations
|
|
||||||
|
|
||||||
class DisplayViewer(UnixViewer):
|
class DisplayViewer(UnixViewer):
|
||||||
|
"""The ImageMagick ``display`` command."""
|
||||||
|
|
||||||
def get_command_ex(self, file, **options):
|
def get_command_ex(self, file, **options):
|
||||||
command = executable = "display"
|
command = executable = "display"
|
||||||
return command, executable
|
return command, executable
|
||||||
|
|
||||||
if shutil.which("display"):
|
|
||||||
register(DisplayViewer)
|
|
||||||
|
|
||||||
class EogViewer(UnixViewer):
|
class EogViewer(UnixViewer):
|
||||||
|
"""The GNOME Image Viewer ``eog`` command."""
|
||||||
|
|
||||||
def get_command_ex(self, file, **options):
|
def get_command_ex(self, file, **options):
|
||||||
command = executable = "eog"
|
command = executable = "eog"
|
||||||
return command, executable
|
return command, executable
|
||||||
|
|
||||||
if shutil.which("eog"):
|
|
||||||
register(EogViewer)
|
|
||||||
|
|
||||||
class XVViewer(UnixViewer):
|
class XVViewer(UnixViewer):
|
||||||
|
"""
|
||||||
|
The X Viewer ``xv`` command.
|
||||||
|
This viewer supports the ``title`` parameter.
|
||||||
|
"""
|
||||||
|
|
||||||
def get_command_ex(self, file, title=None, **options):
|
def get_command_ex(self, file, title=None, **options):
|
||||||
# note: xv is pretty outdated. most modern systems have
|
# note: xv is pretty outdated. most modern systems have
|
||||||
# imagemagick's display command instead.
|
# imagemagick's display command instead.
|
||||||
|
@ -194,6 +218,12 @@ else:
|
||||||
command += " -name %s" % quote(title)
|
command += " -name %s" % quote(title)
|
||||||
return command, executable
|
return command, executable
|
||||||
|
|
||||||
|
|
||||||
|
if sys.platform not in ("win32", "darwin"): # unixoids
|
||||||
|
if shutil.which("display"):
|
||||||
|
register(DisplayViewer)
|
||||||
|
if shutil.which("eog"):
|
||||||
|
register(EogViewer)
|
||||||
if shutil.which("xv"):
|
if shutil.which("xv"):
|
||||||
register(XVViewer)
|
register(XVViewer)
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue
Block a user