diff --git a/PIL/ImageCms.py b/PIL/ImageCms.py index c41139b2b..f966bb676 100644 --- a/PIL/ImageCms.py +++ b/PIL/ImageCms.py @@ -202,7 +202,7 @@ class ImageCmsTransform(Image.ImagePointHandler): ## # (experimental) Fetches the profile for the current display device. -# Returns None if the profile is not known. +# @return None if the profile is not known. def get_display_profile(handle=None): import sys @@ -234,59 +234,50 @@ class PyCMSError(Exception): ## # (pyCMS) Applies an ICC transformation to a given image, mapping from # inputProfile to outputProfile. +# +# If the input or output profiles specified are not valid filenames, a +# PyCMSError will be raised. If inPlace == TRUE and outputMode != im.mode, +# a PyCMSError will be raised. If an error occurs during application of +# the profiles, a PyCMSError will be raised. If outputMode is not a mode +# supported by the outputProfile (or by pyCMS), a PyCMSError will be +# raised. +# +# This function applies an ICC transformation to im from inputProfile's +# color space to outputProfile's color space using the specified rendering +# intent to decide how to handle out-of-gamut colors. +# +# OutputMode can be used to specify that a color mode conversion is to +# be done using these profiles, but the specified profiles must be able +# to handle that mode. I.e., if converting im from RGB to CMYK using +# profiles, the input profile must handle RGB data, and the output +# profile must handle CMYK data. +# +# @param im An open PIL image object (i.e. Image.new(...) or Image.open(...), etc.) +# @param inputProfile String, as a valid filename path to the ICC input profile +# you wish to use for this image, or a profile object +# @param outputProfile String, as a valid filename path to the ICC output +# profile you wish to use for this image, or a profile object +# @param renderingIntent Integer (0-3) specifying the rendering intent you wish +# to use for the transform +# +# INTENT_PERCEPTUAL = 0 (DEFAULT) (ImageCms.INTENT_PERCEPTUAL) +# INTENT_RELATIVE_COLORIMETRIC = 1 (ImageCms.INTENT_RELATIVE_COLORIMETRIC) +# INTENT_SATURATION = 2 (ImageCms.INTENT_SATURATION) +# INTENT_ABSOLUTE_COLORIMETRIC = 3 (ImageCms.INTENT_ABSOLUTE_COLORIMETRIC) +# +# see the pyCMS documentation for details on rendering intents and what they do. +# @param outputMode A valid PIL mode for the output image (i.e. "RGB", "CMYK", +# etc.). Note: if rendering the image "inPlace", outputMode MUST be the +# same mode as the input, or omitted completely. If omitted, the outputMode +# will be the same as the mode of the input image (im.mode) +# @param inPlace Boolean (1 = True, None or 0 = False). If True, the original +# image is modified in-place, and None is returned. If False (default), a +# new Image object is returned with the transform applied. +# @param flags Integer (0-...) specifying additional flags +# @return Either None or a new PIL image object, depending on value of inPlace +# @exception PyCMSError def profileToProfile(im, inputProfile, outputProfile, renderingIntent=INTENT_PERCEPTUAL, outputMode=None, inPlace=0, flags=0): - """ - ImageCms.profileToProfile(im, inputProfile, outputProfile, - [renderingIntent], [outputMode], [inPlace]) - - Returns either None or a new PIL image object, depending on value of - inPlace (see below). - - im = an open PIL image object (i.e. Image.new(...) or - Image.open(...), etc.) - inputProfile = string, as a valid filename path to the ICC input - profile you wish to use for this image, or a profile object - outputProfile = string, as a valid filename path to the ICC output - profile you wish to use for this image, or a profile object - renderingIntent = integer (0-3) specifying the rendering intent you - wish to use for the transform - INTENT_PERCEPTUAL = 0 (DEFAULT) (ImageCms.INTENT_PERCEPTUAL) - INTENT_RELATIVE_COLORIMETRIC =1 (ImageCms.INTENT_RELATIVE_COLORIMETRIC) - INTENT_SATURATION = 2 (ImageCms.INTENT_SATURATION) - INTENT_ABSOLUTE_COLORIMETRIC =3 (ImageCms.INTENT_ABSOLUTE_COLORIMETRIC) - - see the pyCMS documentation for details on rendering intents and - what they do. - outputMode = a valid PIL mode for the output image (i.e. "RGB", "CMYK", - etc.). Note: if rendering the image "inPlace", outputMode MUST be - the same mode as the input, or omitted completely. If omitted, the - outputMode will be the same as the mode of the input image (im.mode) - inPlace = BOOL (1 = TRUE, None or 0 = FALSE). If TRUE, the original - image is modified in-place, and None is returned. If FALSE - (default), a new Image object is returned with the transform - applied. - flags = integer (0-...) specifying additional flags - - If the input or output profiles specified are not valid filenames, a - PyCMSError will be raised. If inPlace == TRUE and outputMode != im.mode, - a PyCMSError will be raised. If an error occurs during application of - the profiles, a PyCMSError will be raised. If outputMode is not a mode - supported by the outputProfile (or by pyCMS), a PyCMSError will be - raised. - - This function applies an ICC transformation to im from inputProfile's - color space to outputProfile's color space using the specified rendering - intent to decide how to handle out-of-gamut colors. - - OutputMode can be used to specify that a color mode conversion is to - be done using these profiles, but the specified profiles must be able - to handle that mode. I.e., if converting im from RGB to CMYK using - profiles, the input profile must handle RGB data, and the output - profile must handle CMYK data. - - """ - if outputMode is None: outputMode = im.mode @@ -316,24 +307,19 @@ def profileToProfile(im, inputProfile, outputProfile, renderingIntent=INTENT_PER ## # (pyCMS) Opens an ICC profile file. +# +# The PyCMSProfile object can be passed back into pyCMS for use in creating +# transforms and such (as in ImageCms.buildTransformFromOpenProfiles()). +# +# If profileFilename is not a vaild filename for an ICC profile, a PyCMSError +# will be raised. +# +# @param profileFilename String, as a valid filename path to the ICC profile you +# wish to open, or a file-like object. +# @return A CmsProfile class object. +# @exception PyCMSError def getOpenProfile(profileFilename): - """ - ImageCms.getOpenProfile(profileFilename) - - Returns a CmsProfile class object. - - profileFilename = string, as a valid filename path to the ICC profile - you wish to open, or a file-like object. - - The PyCMSProfile object can be passed back into pyCMS for use in creating - transforms and such (as in ImageCms.buildTransformFromOpenProfiles()). - - If profileFilename is not a vaild filename for an ICC profile, a - PyCMSError will be raised. - - """ - try: return ImageCmsProfile(profileFilename) except (IOError, TypeError, ValueError) as v: @@ -343,61 +329,56 @@ def getOpenProfile(profileFilename): # (pyCMS) Builds an ICC transform mapping from the inputProfile to the # outputProfile. Use applyTransform to apply the transform to a given # image. +# +# If the input or output profiles specified are not valid filenames, a +# PyCMSError will be raised. If an error occurs during creation of the +# transform, a PyCMSError will be raised. +# +# If inMode or outMode are not a mode supported by the outputProfile (or +# by pyCMS), a PyCMSError will be raised. +# +# This function builds and returns an ICC transform from the inputProfile +# to the outputProfile using the renderingIntent to determine what to do +# with out-of-gamut colors. It will ONLY work for converting images that +# are in inMode to images that are in outMode color format (PIL mode, +# i.e. "RGB", "RGBA", "CMYK", etc.). +# +# Building the transform is a fair part of the overhead in +# ImageCms.profileToProfile(), so if you're planning on converting multiple +# images using the same input/output settings, this can save you time. +# Once you have a transform object, it can be used with +# ImageCms.applyProfile() to convert images without the need to re-compute +# the lookup table for the transform. +# +# The reason pyCMS returns a class object rather than a handle directly +# to the transform is that it needs to keep track of the PIL input/output +# modes that the transform is meant for. These attributes are stored in +# the "inMode" and "outMode" attributes of the object (which can be +# manually overridden if you really want to, but I don't know of any +# time that would be of use, or would even work). +# +# @param inputProfile String, as a valid filename path to the ICC input profile +# you wish to use for this transform, or a profile object +# @param outputProfile String, as a valid filename path to the ICC output +# profile you wish to use for this transform, or a profile object +# @param inMode String, as a valid PIL mode that the appropriate profile also +# supports (i.e. "RGB", "RGBA", "CMYK", etc.) +# @param outMode String, as a valid PIL mode that the appropriate profile also +# supports (i.e. "RGB", "RGBA", "CMYK", etc.) +# @param renderingIntent Integer (0-3) specifying the rendering intent you +# wish to use for the transform +# +# INTENT_PERCEPTUAL = 0 (DEFAULT) (ImageCms.INTENT_PERCEPTUAL) +# INTENT_RELATIVE_COLORIMETRIC = 1 (ImageCms.INTENT_RELATIVE_COLORIMETRIC) +# INTENT_SATURATION = 2 (ImageCms.INTENT_SATURATION) +# INTENT_ABSOLUTE_COLORIMETRIC = 3 (ImageCms.INTENT_ABSOLUTE_COLORIMETRIC) +# +# see the pyCMS documentation for details on rendering intents and what they do. +# @param flags Integer (0-...) specifying additional flags +# @return A CmsTransform class object. +# @exception PyCMSError def buildTransform(inputProfile, outputProfile, inMode, outMode, renderingIntent=INTENT_PERCEPTUAL, flags=0): - """ - ImageCms.buildTransform(inputProfile, outputProfile, inMode, outMode, - [renderingIntent]) - - Returns a CmsTransform class object. - - inputProfile = string, as a valid filename path to the ICC input - profile you wish to use for this transform, or a profile object - outputProfile = string, as a valid filename path to the ICC output - profile you wish to use for this transform, or a profile object - inMode = string, as a valid PIL mode that the appropriate profile also - supports (i.e. "RGB", "RGBA", "CMYK", etc.) - outMode = string, as a valid PIL mode that the appropriate profile also - supports (i.e. "RGB", "RGBA", "CMYK", etc.) - renderingIntent = integer (0-3) specifying the rendering intent you - wish to use for the transform - INTENT_PERCEPTUAL = 0 (DEFAULT) (ImageCms.INTENT_PERCEPTUAL) - INTENT_RELATIVE_COLORIMETRIC =1 (ImageCms.INTENT_RELATIVE_COLORIMETRIC) - INTENT_SATURATION = 2 (ImageCms.INTENT_SATURATION) - INTENT_ABSOLUTE_COLORIMETRIC =3 (ImageCms.INTENT_ABSOLUTE_COLORIMETRIC) - see the pyCMS documentation for details on rendering intents and - what they do. - flags = integer (0-...) specifying additional flags - - If the input or output profiles specified are not valid filenames, a - PyCMSError will be raised. If an error occurs during creation of the - transform, a PyCMSError will be raised. - - If inMode or outMode are not a mode supported by the outputProfile (or - by pyCMS), a PyCMSError will be raised. - - This function builds and returns an ICC transform from the inputProfile - to the outputProfile using the renderingIntent to determine what to do - with out-of-gamut colors. It will ONLY work for converting images that - are in inMode to images that are in outMode color format (PIL mode, - i.e. "RGB", "RGBA", "CMYK", etc.). - - Building the transform is a fair part of the overhead in - ImageCms.profileToProfile(), so if you're planning on converting multiple - images using the same input/output settings, this can save you time. - Once you have a transform object, it can be used with - ImageCms.applyProfile() to convert images without the need to re-compute - the lookup table for the transform. - - The reason pyCMS returns a class object rather than a handle directly - to the transform is that it needs to keep track of the PIL input/output - modes that the transform is meant for. These attributes are stored in - the "inMode" and "outMode" attributes of the object (which can be - manually overridden if you really want to, but I don't know of any - time that would be of use, or would even work). - - """ - if not isinstance(renderingIntent, int) or not (0 <= renderingIntent <=3): raise PyCMSError("renderingIntent must be an integer between 0 and 3") @@ -417,78 +398,74 @@ def buildTransform(inputProfile, outputProfile, inMode, outMode, renderingIntent # (pyCMS) Builds an ICC transform mapping from the inputProfile to the # outputProfile, but tries to simulate the result that would be # obtained on the proofProfile device. +# +# If the input, output, or proof profiles specified are not valid +# filenames, a PyCMSError will be raised. +# +# If an error occurs during creation of the transform, a PyCMSError will +# be raised. +# +# If inMode or outMode are not a mode supported by the outputProfile +# (or by pyCMS), a PyCMSError will be raised. +# +# This function builds and returns an ICC transform from the inputProfile +# to the outputProfile, but tries to simulate the result that would be +# obtained on the proofProfile device using renderingIntent and +# proofRenderingIntent to determine what to do with out-of-gamut +# colors. This is known as "soft-proofing". It will ONLY work for +# converting images that are in inMode to images that are in outMode +# color format (PIL mode, i.e. "RGB", "RGBA", "CMYK", etc.). +# +# Usage of the resulting transform object is exactly the same as with +# ImageCms.buildTransform(). +# +# Proof profiling is generally used when using an output device to get a +# good idea of what the final printed/displayed image would look like on +# the proofProfile device when it's quicker and easier to use the +# output device for judging color. Generally, this means that the +# output device is a monitor, or a dye-sub printer (etc.), and the simulated +# device is something more expensive, complicated, or time consuming +# (making it difficult to make a real print for color judgement purposes). +# +# Soft-proofing basically functions by adjusting the colors on the +# output device to match the colors of the device being simulated. However, +# when the simulated device has a much wider gamut than the output +# device, you may obtain marginal results. +# +# @param inputProfile String, as a valid filename path to the ICC input profile +# you wish to use for this transform, or a profile object +# @param outputProfile String, as a valid filename path to the ICC output +# (monitor, usually) profile you wish to use for this transform, or a +# profile object +# @param proofProfile String, as a valid filename path to the ICC proof profile +# you wish to use for this transform, or a profile object +# @param inMode String, as a valid PIL mode that the appropriate profile also +# supports (i.e. "RGB", "RGBA", "CMYK", etc.) +# @param outMode String, as a valid PIL mode that the appropriate profile also +# supports (i.e. "RGB", "RGBA", "CMYK", etc.) +# @param renderingIntent Integer (0-3) specifying the rendering intent you +# wish to use for the input->proof (simulated) transform +# +# INTENT_PERCEPTUAL = 0 (DEFAULT) (ImageCms.INTENT_PERCEPTUAL) +# INTENT_RELATIVE_COLORIMETRIC = 1 (ImageCms.INTENT_RELATIVE_COLORIMETRIC) +# INTENT_SATURATION = 2 (ImageCms.INTENT_SATURATION) +# INTENT_ABSOLUTE_COLORIMETRIC = 3 (ImageCms.INTENT_ABSOLUTE_COLORIMETRIC) +# +# see the pyCMS documentation for details on rendering intents and what they do. +# @param proofRenderingIntent Integer (0-3) specifying the rendering intent you +# wish to use for proof->output transform +# +# INTENT_PERCEPTUAL = 0 (DEFAULT) (ImageCms.INTENT_PERCEPTUAL) +# INTENT_RELATIVE_COLORIMETRIC = 1 (ImageCms.INTENT_RELATIVE_COLORIMETRIC) +# INTENT_SATURATION = 2 (ImageCms.INTENT_SATURATION) +# INTENT_ABSOLUTE_COLORIMETRIC = 3 (ImageCms.INTENT_ABSOLUTE_COLORIMETRIC) +# +# see the pyCMS documentation for details on rendering intents and what they do. +# @param flags Integer (0-...) specifying additional flags +# @return A CmsTransform class object. +# @exception PyCMSError def buildProofTransform(inputProfile, outputProfile, proofProfile, inMode, outMode, renderingIntent=INTENT_PERCEPTUAL, proofRenderingIntent=INTENT_ABSOLUTE_COLORIMETRIC, flags=FLAGS["SOFTPROOFING"]): - """ - ImageCms.buildProofTransform(inputProfile, outputProfile, proofProfile, - inMode, outMode, [renderingIntent], [proofRenderingIntent]) - - Returns a CmsTransform class object. - - inputProfile = string, as a valid filename path to the ICC input - profile you wish to use for this transform, or a profile object - outputProfile = string, as a valid filename path to the ICC output - (monitor, usually) profile you wish to use for this transform, - or a profile object - proofProfile = string, as a valid filename path to the ICC proof - profile you wish to use for this transform, or a profile object - inMode = string, as a valid PIL mode that the appropriate profile also - supports (i.e. "RGB", "RGBA", "CMYK", etc.) - outMode = string, as a valid PIL mode that the appropriate profile also - supports (i.e. "RGB", "RGBA", "CMYK", etc.) - renderingIntent = integer (0-3) specifying the rendering intent you - wish to use for the input->proof (simulated) transform - INTENT_PERCEPTUAL = 0 (DEFAULT) (ImageCms.INTENT_PERCEPTUAL) - INTENT_RELATIVE_COLORIMETRIC =1 (ImageCms.INTENT_RELATIVE_COLORIMETRIC) - INTENT_SATURATION = 2 (ImageCms.INTENT_SATURATION) - INTENT_ABSOLUTE_COLORIMETRIC =3 (ImageCms.INTENT_ABSOLUTE_COLORIMETRIC) - see the pyCMS documentation for details on rendering intents and - what they do. - proofRenderingIntent = integer (0-3) specifying the rendering intent - you wish to use for proof->output transform - INTENT_PERCEPTUAL = 0 (DEFAULT) (ImageCms.INTENT_PERCEPTUAL) - INTENT_RELATIVE_COLORIMETRIC =1 (ImageCms.INTENT_RELATIVE_COLORIMETRIC) - INTENT_SATURATION = 2 (ImageCms.INTENT_SATURATION) - INTENT_ABSOLUTE_COLORIMETRIC =3 (ImageCms.INTENT_ABSOLUTE_COLORIMETRIC) - see the pyCMS documentation for details on rendering intents and - what they do. - flags = integer (0-...) specifying additional flags - - If the input, output, or proof profiles specified are not valid - filenames, a PyCMSError will be raised. - - If an error occurs during creation of the transform, a PyCMSError will - be raised. - - If inMode or outMode are not a mode supported by the outputProfile - (or by pyCMS), a PyCMSError will be raised. - - This function builds and returns an ICC transform from the inputProfile - to the outputProfile, but tries to simulate the result that would be - obtained on the proofProfile device using renderingIntent and - proofRenderingIntent to determine what to do with out-of-gamut - colors. This is known as "soft-proofing". It will ONLY work for - converting images that are in inMode to images that are in outMode - color format (PIL mode, i.e. "RGB", "RGBA", "CMYK", etc.). - - Usage of the resulting transform object is exactly the same as with - ImageCms.buildTransform(). - - Proof profiling is generally used when using an output device to get a - good idea of what the final printed/displayed image would look like on - the proofProfile device when it's quicker and easier to use the - output device for judging color. Generally, this means that the - output device is a monitor, or a dye-sub printer (etc.), and the simulated - device is something more expensive, complicated, or time consuming - (making it difficult to make a real print for color judgement purposes). - - Soft-proofing basically functions by adjusting the colors on the - output device to match the colors of the device being simulated. However, - when the simulated device has a much wider gamut than the output - device, you may obtain marginal results. - - """ - if not isinstance(renderingIntent, int) or not (0 <= renderingIntent <=3): raise PyCMSError("renderingIntent must be an integer between 0 and 3") @@ -511,48 +488,41 @@ buildProofTransformFromOpenProfiles = buildProofTransform ## # (pyCMS) Applies a transform to a given image. +# +# If im.mode != transform.inMode, a PyCMSError is raised. +# +# If inPlace == TRUE and transform.inMode != transform.outMode, a +# PyCMSError is raised. +# +# If im.mode, transfer.inMode, or transfer.outMode is not supported by +# pyCMSdll or the profiles you used for the transform, a PyCMSError is +# raised. +# +# If an error occurs while the transform is being applied, a PyCMSError +# is raised. +# +# This function applies a pre-calculated transform (from +# ImageCms.buildTransform() or ImageCms.buildTransformFromOpenProfiles()) to an +# image. The transform can be used for multiple images, saving +# considerable calcuation time if doing the same conversion multiple times. +# +# If you want to modify im in-place instead of receiving a new image as +# the return value, set inPlace to TRUE. This can only be done if +# transform.inMode and transform.outMode are the same, because we can't +# change the mode in-place (the buffer sizes for some modes are +# different). The default behavior is to return a new Image object of +# the same dimensions in mode transform.outMode. +# +# @param im A PIL Image object, and im.mode must be the same as the inMode +# supported by the transform. +# @param transform A valid CmsTransform class object +# @param inPlace Bool (1 == True, 0 or None == False). If True, im is modified +# in place and None is returned, if False, a new Image object with the +# transform applied is returned (and im is not changed). The default is False. +# @return Either None, or a new PIL Image object, depending on the value of inPlace +# @exception PyCMSError def applyTransform(im, transform, inPlace=0): - """ - ImageCms.applyTransform(im, transform, [inPlace]) - - Returns either None, or a new PIL Image object, depending on the value - of inPlace (see below) - - im = a PIL Image object, and im.mode must be the same as the inMode - supported by the transform. - transform = a valid CmsTransform class object - inPlace = BOOL (1 == TRUE, 0 or None == FALSE). If TRUE, im is - modified in place and None is returned, if FALSE, a new Image - object with the transform applied is returned (and im is not - changed). The default is FALSE. - - If im.mode != transform.inMode, a PyCMSError is raised. - - If inPlace == TRUE and transform.inMode != transform.outMode, a - PyCMSError is raised. - - If im.mode, transfer.inMode, or transfer.outMode is not supported by - pyCMSdll or the profiles you used for the transform, a PyCMSError is - raised. - - If an error occurs while the transform is being applied, a PyCMSError - is raised. - - This function applies a pre-calculated transform (from - ImageCms.buildTransform() or ImageCms.buildTransformFromOpenProfiles()) to an - image. The transform can be used for multiple images, saving - considerable calcuation time if doing the same conversion multiple times. - - If you want to modify im in-place instead of receiving a new image as - the return value, set inPlace to TRUE. This can only be done if - transform.inMode and transform.outMode are the same, because we can't - change the mode in-place (the buffer sizes for some modes are - different). The default behavior is to return a new Image object of - the same dimensions in mode transform.outMode. - - """ - try: if inPlace: transform.apply_in_place(im) @@ -566,33 +536,29 @@ def applyTransform(im, transform, inPlace=0): ## # (pyCMS) Creates a profile. +# +# If colorSpace not in ["LAB", "XYZ", "sRGB"], a PyCMSError is raised +# +# If using LAB and colorTemp != a positive integer, a PyCMSError is raised. +# +# If an error occurs while creating the profile, a PyCMSError is raised. +# +# Use this function to create common profiles on-the-fly instead of +# having to supply a profile on disk and knowing the path to it. It +# returns a normal CmsProfile object that can be passed to +# ImageCms.buildTransformFromOpenProfiles() to create a transform to apply +# to images. +# +# @param colorSpace String, the color space of the profile you wish to create. +# Currently only "LAB", "XYZ", and "sRGB" are supported. +# @param colorTemp Positive integer for the white point for the profile, in +# degrees Kelvin (i.e. 5000, 6500, 9600, etc.). The default is for D50 +# illuminant if omitted (5000k). colorTemp is ONLY applied to LAB profiles, +# and is ignored for XYZ and sRGB. +# @return A CmsProfile class object +# @exception PyCMSError def createProfile(colorSpace, colorTemp=-1): - """ - ImageCms.createProfile(colorSpace, [colorTemp]) - - Returns a CmsProfile class object - - colorSpace = string, the color space of the profile you wish to create. - Currently only "LAB", "XYZ", and "sRGB" are supported. - colorTemp = positive integer for the white point for the profile, in - degrees Kelvin (i.e. 5000, 6500, 9600, etc.). The default is for - D50 illuminant if omitted (5000k). colorTemp is ONLY applied to - LAB profiles, and is ignored for XYZ and sRGB. - - If colorSpace not in ["LAB", "XYZ", "sRGB"], a PyCMSError is raised - - If using LAB and colorTemp != a positive integer, a PyCMSError is raised. - - If an error occurs while creating the profile, a PyCMSError is raised. - - Use this function to create common profiles on-the-fly instead of - having to supply a profile on disk and knowing the path to it. It - returns a normal CmsProfile object that can be passed to - ImageCms.buildTransformFromOpenProfiles() to create a transform to apply - to images. - - """ if colorSpace not in ["LAB", "XYZ", "sRGB"]: raise PyCMSError("Color space not supported for on-the-fly profile creation (%s)" % colorSpace) @@ -609,27 +575,23 @@ def createProfile(colorSpace, colorTemp=-1): ## # (pyCMS) Gets the internal product name for the given profile. +# +# If profile isn't a valid CmsProfile object or filename to a profile, +# a PyCMSError is raised If an error occurs while trying to obtain the +# name tag, a PyCMSError is raised. +# +# Use this function to obtain the INTERNAL name of the profile (stored +# in an ICC tag in the profile itself), usually the one used when the +# profile was originally created. Sometimes this tag also contains +# additional information supplied by the creator. +# +# @param profile EITHER a valid CmsProfile object, OR a string of the filename +# of an ICC profile. +# @return A string containing the internal name of the profile as stored in an +# ICC tag. +# @exception PyCMSError def getProfileName(profile): - """ - ImageCms.getProfileName(profile) - - Returns a string containing the internal name of the profile as stored - in an ICC tag. - - profile = EITHER a valid CmsProfile object, OR a string of the - filename of an ICC profile. - - If profile isn't a valid CmsProfile object or filename to a profile, - a PyCMSError is raised If an error occurs while trying to obtain the - name tag, a PyCMSError is raised. - - Use this function to obtain the INTERNAL name of the profile (stored - in an ICC tag in the profile itself), usually the one used when the - profile was originally created. Sometimes this tag also contains - additional information supplied by the creator. - - """ try: # add an extra newline to preserve pyCMS compatibility if not isinstance(profile, ImageCmsProfile): @@ -640,28 +602,24 @@ def getProfileName(profile): ## # (pyCMS) Gets the internal product information for the given profile. +# +# If profile isn't a valid CmsProfile object or filename to a profile, +# a PyCMSError is raised. +# +# If an error occurs while trying to obtain the info tag, a PyCMSError +# is raised +# +# Use this function to obtain the information stored in the profile's +# info tag. This often contains details about the profile, and how it +# was created, as supplied by the creator. +# +# @param profile EITHER a valid CmsProfile object, OR a string of the filename +# of an ICC profile. +# @return A string containing the internal profile information stored in an ICC +# tag. +# @exception PyCMSError def getProfileInfo(profile): - """ - ImageCms.getProfileInfo(profile) - - Returns a string containing the internal profile information stored in - an ICC tag. - - profile = EITHER a valid CmsProfile object, OR a string of the - filename of an ICC profile. - - If profile isn't a valid CmsProfile object or filename to a profile, - a PyCMSError is raised. - - If an error occurs while trying to obtain the info tag, a PyCMSError - is raised - - Use this function to obtain the information stored in the profile's - info tag. This often contains details about the profile, and how it - was created, as supplied by the creator. - - """ try: if not isinstance(profile, ImageCmsProfile): profile = ImageCmsProfile(profile) @@ -672,35 +630,32 @@ def getProfileInfo(profile): ## # (pyCMS) Gets the default intent name for the given profile. +# +# If profile isn't a valid CmsProfile object or filename to a profile, +# a PyCMSError is raised. +# +# If an error occurs while trying to obtain the default intent, a +# PyCMSError is raised. +# +# Use this function to determine the default (and usually best optomized) +# rendering intent for this profile. Most profiles support multiple +# rendering intents, but are intended mostly for one type of conversion. +# If you wish to use a different intent than returned, use +# ImageCms.isIntentSupported() to verify it will work first. +# +# @param profile EITHER a valid CmsProfile object, OR a string of the filename +# of an ICC profile. +# @return Integer 0-3 specifying the default rendering intent for this profile. +# +# INTENT_PERCEPTUAL = 0 (DEFAULT) (ImageCms.INTENT_PERCEPTUAL) +# INTENT_RELATIVE_COLORIMETRIC = 1 (ImageCms.INTENT_RELATIVE_COLORIMETRIC) +# INTENT_SATURATION = 2 (ImageCms.INTENT_SATURATION) +# INTENT_ABSOLUTE_COLORIMETRIC = 3 (ImageCms.INTENT_ABSOLUTE_COLORIMETRIC) +# +# see the pyCMS documentation for details on rendering intents and what they do. +# @exception PyCMSError def getDefaultIntent(profile): - """ - ImageCms.getDefaultIntent(profile) - - Returns integer 0-3 specifying the default rendering intent for this - profile. - INTENT_PERCEPTUAL = 0 (DEFAULT) (ImageCms.INTENT_PERCEPTUAL) - INTENT_RELATIVE_COLORIMETRIC =1 (ImageCms.INTENT_RELATIVE_COLORIMETRIC) - INTENT_SATURATION = 2 (ImageCms.INTENT_SATURATION) - INTENT_ABSOLUTE_COLORIMETRIC =3 (ImageCms.INTENT_ABSOLUTE_COLORIMETRIC) - see the pyCMS documentation for details on rendering intents and - what they do. - - profile = EITHER a valid CmsProfile object, OR a string of the - filename of an ICC profile. - - If profile isn't a valid CmsProfile object or filename to a profile, - a PyCMSError is raised. - - If an error occurs while trying to obtain the default intent, a - PyCMSError is raised. - - Use this function to determine the default (and usually best optomized) - rendering intent for this profile. Most profiles support multiple - rendering intents, but are intended mostly for one type of conversion. - If you wish to use a different intent than returned, use - ImageCms.isIntentSupported() to verify it will work first. - """ try: if not isinstance(profile, ImageCmsProfile): profile = ImageCmsProfile(profile) @@ -710,41 +665,40 @@ def getDefaultIntent(profile): ## # (pyCMS) Checks if a given intent is supported. +# +# Use this function to verify that you can use your desired +# renderingIntent with profile, and that profile can be used for the +# input/output/proof profile as you desire. +# +# Some profiles are created specifically for one "direction", can cannot +# be used for others. Some profiles can only be used for certain +# rendering intents... so it's best to either verify this before trying +# to create a transform with them (using this function), or catch the +# potential PyCMSError that will occur if they don't support the modes +# you select. +# +# @param profile EITHER a valid CmsProfile object, OR a string of the filename +# of an ICC profile. +# @param intent Integer (0-3) specifying the rendering intent you wish to use +# with this profile +# +# INTENT_PERCEPTUAL = 0 (DEFAULT) (ImageCms.INTENT_PERCEPTUAL) +# INTENT_RELATIVE_COLORIMETRIC = 1 (ImageCms.INTENT_RELATIVE_COLORIMETRIC) +# INTENT_SATURATION = 2 (ImageCms.INTENT_SATURATION) +# INTENT_ABSOLUTE_COLORIMETRIC = 3 (ImageCms.INTENT_ABSOLUTE_COLORIMETRIC) +# +# see the pyCMS documentation for details on rendering intents and what they do. +# @param direction Integer specifing if the profile is to be used for input, +# output, or proof +# +# INPUT = 0 (or use ImageCms.DIRECTION_INPUT) +# OUTPUT = 1 (or use ImageCms.DIRECTION_OUTPUT) +# PROOF = 2 (or use ImageCms.DIRECTION_PROOF) +# +# @return 1 if the intent/direction are supported, -1 if they are not. +# @exception PyCMSError def isIntentSupported(profile, intent, direction): - """ - ImageCms.isIntentSupported(profile, intent, direction) - - Returns 1 if the intent/direction are supported, -1 if they are not. - - profile = EITHER a valid CmsProfile object, OR a string of the - filename of an ICC profile. - intent = integer (0-3) specifying the rendering intent you wish to use - with this profile - INTENT_PERCEPTUAL = 0 (DEFAULT) (ImageCms.INTENT_PERCEPTUAL) - INTENT_RELATIVE_COLORIMETRIC =1 (ImageCms.INTENT_RELATIVE_COLORIMETRIC) - INTENT_SATURATION = 2 (ImageCms.INTENT_SATURATION) - INTENT_ABSOLUTE_COLORIMETRIC =3 (ImageCms.INTENT_ABSOLUTE_COLORIMETRIC) - see the pyCMS documentation for details on rendering intents and - what they do. - direction = integer specifing if the profile is to be used for input, - output, or proof - INPUT = 0 (or use ImageCms.DIRECTION_INPUT) - OUTPUT = 1 (or use ImageCms.DIRECTION_OUTPUT) - PROOF = 2 (or use ImageCms.DIRECTION_PROOF) - - Use this function to verify that you can use your desired - renderingIntent with profile, and that profile can be used for the - input/output/proof profile as you desire. - - Some profiles are created specifically for one "direction", can cannot - be used for others. Some profiles can only be used for certain - rendering intents... so it's best to either verify this before trying - to create a transform with them (using this function), or catch the - potential PyCMSError that will occur if they don't support the modes - you select. - - """ try: if not isinstance(profile, ImageCmsProfile): profile = ImageCmsProfile(profile) diff --git a/PIL/JpegPresets.py b/PIL/JpegPresets.py index 1df6f0ba3..b664755e8 100644 --- a/PIL/JpegPresets.py +++ b/PIL/JpegPresets.py @@ -5,21 +5,21 @@ More presets can be added to the presets dict if needed. Can be use when saving JPEG file. -To apply the preset, specify: +To apply the preset, specify:: - - quality=preset name - -To apply only the quantization table: + quality="preset_name" -- qtables=preset name +To apply only the quantization table:: -To apply only the subsampling setting: + qtables="preset_name" -- subsampling=preset name +To apply only the subsampling setting:: -Example: + subsampling="preset_name" - im.save("image_name.jpg", quality="web_high") +Example:: + + im.save("image_name.jpg", quality="web_high") Subsampling @@ -28,7 +28,7 @@ Subsampling Subsampling is the practice of encoding images by implementing less resolution for chroma information than for luma information. (ref.: http://en.wikipedia.org/wiki/Chroma_subsampling) - + Possible subsampling values are 0, 1 and 2 that correspond to 4:4:4, 4:2:2 and 4:1:1 (or 4:2:0?). @@ -42,25 +42,23 @@ Quantization tables They are values use by the DCT (Discrete cosine transform) to remove *unnecessary* information from the image (the lossy part of the compression). (ref.: http://en.wikipedia.org/wiki/Quantization_matrix#Quantization_matrices, - http://en.wikipedia.org/wiki/JPEG#Quantization) +http://en.wikipedia.org/wiki/JPEG#Quantization) -You can get the quantization tables of a JPEG with: +You can get the quantization tables of a JPEG with:: + + im.quantization - im.quantization - This will return a dict with a number of arrays. You can pass this dict directly as the qtables argument when saving a JPEG. The tables format between im.quantization and quantization in presets differ in 3 ways: - 1. The base container of the preset is a list with sublists instead of dict. - dict[0] -> list[0], dict[1] -> list[1], ... - - 2. Each table in a preset is a list instead of an array. - - 3. The zigzag order is remove in the preset (needed by libjpeg >= 6a). - +1. The base container of the preset is a list with sublists instead of dict. + dict[0] -> list[0], dict[1] -> list[1], ... +2. Each table in a preset is a list instead of an array. +3. The zigzag order is remove in the preset (needed by libjpeg >= 6a). + You can convert the dict format to the preset format with the `JpegImagePlugin.convert_dict_qtables(dict_qtables)` function. @@ -68,7 +66,7 @@ Libjpeg ref.: http://www.jpegcameras.com/libjpeg/libjpeg-3.html """ -presets = { +presets = { 'web_low': {'subsampling': 2, # "4:1:1" 'quantization': [ [20, 16, 25, 39, 50, 46, 62, 68, @@ -88,7 +86,6 @@ presets = { 68, 68, 68, 68, 68, 68, 68, 68, 68, 68, 68, 68, 68, 68, 68, 68] ]}, - 'web_medium': {'subsampling': 2, # "4:1:1" 'quantization': [ [16, 11, 11, 16, 23, 27, 31, 30, @@ -108,7 +105,6 @@ presets = { 38, 35, 46, 53, 64, 64, 64, 64, 48, 43, 53, 64, 64, 64, 64, 64] ]}, - 'web_high': {'subsampling': 0, # "4:4:4" 'quantization': [ [ 6, 4, 4, 6, 9, 11, 12, 16, @@ -128,7 +124,6 @@ presets = { 31, 31, 31, 31, 31, 31, 31, 31, 31, 31, 31, 31, 31, 31, 31, 31] ]}, - 'web_very_high': {'subsampling': 0, # "4:4:4" 'quantization': [ [ 2, 2, 2, 2, 3, 4, 5, 6, @@ -148,7 +143,6 @@ presets = { 15, 12, 12, 12, 12, 12, 12, 12, 15, 12, 12, 12, 12, 12, 12, 12] ]}, - 'web_maximum': {'subsampling': 0, # "4:4:4" 'quantization': [ [ 1, 1, 1, 1, 1, 1, 1, 1, @@ -168,7 +162,6 @@ presets = { 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3] ]}, - 'low': {'subsampling': 2, # "4:1:1" 'quantization': [ [18, 14, 14, 21, 30, 35, 34, 17, @@ -207,7 +200,6 @@ presets = { 17, 12, 12, 12, 12, 12, 12, 12, 17, 12, 12, 12, 12, 12, 12, 12] ]}, - 'high': {'subsampling': 0, # "4:4:4" 'quantization': [ [ 6, 4, 4, 6, 9, 11, 12, 16, @@ -227,7 +219,6 @@ presets = { 17, 12, 12, 12, 12, 12, 12, 12, 17, 12, 12, 12, 12, 12, 12, 12] ]}, - 'maximum': {'subsampling': 0, # "4:4:4" 'quantization': [ [ 2, 2, 2, 2, 3, 4, 5, 6, @@ -247,4 +238,4 @@ presets = { 15, 12, 12, 12, 12, 12, 12, 12, 15, 12, 12, 12, 12, 12, 12, 12] ]}, - } \ No newline at end of file +} \ No newline at end of file diff --git a/PIL/OleFileIO.py b/PIL/OleFileIO.py index 1976df6c2..4d26ceb87 100644 --- a/PIL/OleFileIO.py +++ b/PIL/OleFileIO.py @@ -239,7 +239,7 @@ class OleFileIO: Object names are given as a list of strings, one for each subentry level. The root entry should be omitted. For example, the following - code extracts all image streams from a Microsoft Image Composer file: + code extracts all image streams from a Microsoft Image Composer file:: ole = OleFileIO("fan.mic")