From 688c8dd53833ef8bab033ea3be74e5ded78e988f Mon Sep 17 00:00:00 2001 From: wiredfool Date: Thu, 3 Apr 2014 15:47:57 -0700 Subject: [PATCH] comment ->autodoc transform --- PIL/ImageCms.py | 869 ++++++++++++++++++++++++------------------------ 1 file changed, 440 insertions(+), 429 deletions(-) diff --git a/PIL/ImageCms.py b/PIL/ImageCms.py index 9d9f7f07b..ec891d0e5 100644 --- a/PIL/ImageCms.py +++ b/PIL/ImageCms.py @@ -165,11 +165,10 @@ class ImageCmsProfile: self.product_name = None self.product_info = None -## -# Transform. This can be used with the procedural API, or with the -# standard {@link Image.point} method. - class ImageCmsTransform(Image.ImagePointHandler): + """Transform. This can be used with the procedural API, or with the + standard Image.point() method. + """ def __init__(self, input, output, input_mode, output_mode, intent=INTENT_PERCEPTUAL, @@ -209,11 +208,11 @@ class ImageCmsTransform(Image.ImagePointHandler): result = self.transform.apply(im.im.id, im.im.id) return im -## -# (experimental) Fetches the profile for the current display device. -# @return None if the profile is not known. - def get_display_profile(handle=None): + """ (experimental) Fetches the profile for the current display device. + :returns: None if the profile is not known. + """ + import sys if sys.platform == "win32": from PIL import ImageWin @@ -234,59 +233,58 @@ def get_display_profile(handle=None): # pyCMS compatible layer # --------------------------------------------------------------------. -## -# (pyCMS) Exception class. This is used for all errors in the pyCMS API. - class PyCMSError(Exception): + """ (pyCMS) Exception class. This is used for all errors in the pyCMS API. """ pass -## -# (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): + """ + (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 + :returns: Either None or a new PIL image object, depending on value of inPlace + :exception PyCMSError: + """ + if outputMode is None: outputMode = im.mode @@ -314,80 +312,83 @@ def profileToProfile(im, inputProfile, outputProfile, renderingIntent=INTENT_PER return imOut -## -# (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): + """ + (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. + :returns: A CmsProfile class object. + :exception PyCMSError: + """ + try: return ImageCmsProfile(profileFilename) except (IOError, TypeError, ValueError) as v: raise PyCMSError(v) -## -# (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): + """ + (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 + :returns: A CmsTransform class object. + :exception PyCMSError: + """ + if not isinstance(renderingIntent, int) or not (0 <= renderingIntent <=3): raise PyCMSError("renderingIntent must be an integer between 0 and 3") @@ -403,78 +404,79 @@ def buildTransform(inputProfile, outputProfile, inMode, outMode, renderingIntent except (IOError, TypeError, ValueError) as v: raise PyCMSError(v) -## -# (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"]): + """ + (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 + :returns: A CmsTransform class object. + :exception PyCMSError: + """ + if not isinstance(renderingIntent, int) or not (0 <= renderingIntent <=3): raise PyCMSError("renderingIntent must be an integer between 0 and 3") @@ -495,43 +497,44 @@ def buildProofTransform(inputProfile, outputProfile, proofProfile, inMode, outMo buildTransformFromOpenProfiles = buildTransform 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): + """ + (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. + :returns: Either None, or a new PIL Image object, depending on the value of inPlace + :exception PyCMSError: + """ + try: if inPlace: transform.apply_in_place(im) @@ -543,31 +546,32 @@ def applyTransform(im, transform, inPlace=0): return imOut -## -# (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): + """ + (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. + :returns: A CmsProfile class object + :exception PyCMSError: + """ + if colorSpace not in ["LAB", "XYZ", "sRGB"]: raise PyCMSError("Color space not supported for on-the-fly profile creation (%s)" % colorSpace) @@ -582,25 +586,27 @@ def createProfile(colorSpace, colorTemp=-1): except (TypeError, ValueError) as v: raise PyCMSError(v) -## -# (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): + """ + + (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. + :returns: A string containing the internal name of the profile as stored in an + ICC tag. + :exception PyCMSError: + """ + try: # add an extra newline to preserve pyCMS compatibility if not isinstance(profile, ImageCmsProfile): @@ -621,26 +627,27 @@ def getProfileName(profile): except (AttributeError, IOError, TypeError, ValueError) as v: raise PyCMSError(v) -## -# (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): + """ + (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. + :returns: A string containing the internal profile information stored in an ICC + tag. + :exception PyCMSError: + """ + try: if not isinstance(profile, ImageCmsProfile): profile = ImageCmsProfile(profile) @@ -659,25 +666,25 @@ def getProfileInfo(profile): raise PyCMSError(v) -## -# (pyCMS) Gets the copyright 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 copyright tag, a PyCMSError -# is raised -# -# Use this function to obtain the information stored in the profile's -# copyright tag. -# -# @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 getProfileCopyright(profile): + """ + (pyCMS) Gets the copyright 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 copyright tag, a PyCMSError + is raised + + Use this function to obtain the information stored in the profile's + copyright tag. + + :param profile: EITHER a valid CmsProfile object, OR a string of the filename + of an ICC profile. + :returns: A string containing the internal profile information stored in an ICC + tag. + :exception PyCMSError: + """ try: # add an extra newline to preserve pyCMS compatibility if not isinstance(profile, ImageCmsProfile): @@ -686,25 +693,25 @@ def getProfileCopyright(profile): except (AttributeError, IOError, TypeError, ValueError) as v: raise PyCMSError(v) -## -# (pyCMS) Gets the manufacturer 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 manufacturer tag, a PyCMSError -# is raised -# -# Use this function to obtain the information stored in the profile's -# manufacturer tag. -# -# @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 getProfileManufacturer(profile): + """ + (pyCMS) Gets the manufacturer 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 manufacturer tag, a PyCMSError + is raised + + Use this function to obtain the information stored in the profile's + manufacturer tag. + + :param profile: EITHER a valid CmsProfile object, OR a string of the filename + of an ICC profile. + :returns: A string containing the internal profile information stored in an ICC + tag. + :exception PyCMSError: + """ try: # add an extra newline to preserve pyCMS compatibility if not isinstance(profile, ImageCmsProfile): @@ -713,25 +720,26 @@ def getProfileManufacturer(profile): except (AttributeError, IOError, TypeError, ValueError) as v: raise PyCMSError(v) -## -# (pyCMS) Gets the model 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 model tag, a PyCMSError -# is raised -# -# Use this function to obtain the information stored in the profile's -# model tag. -# -# @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 getProfileModel(profile): + """ + (pyCMS) Gets the model 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 model tag, a PyCMSError + is raised + + Use this function to obtain the information stored in the profile's + model tag. + + :param profile: EITHER a valid CmsProfile object, OR a string of the filename + of an ICC profile. + :returns: A string containing the internal profile information stored in an ICC + tag. + :exception PyCMSError: + """ + try: # add an extra newline to preserve pyCMS compatibility if not isinstance(profile, ImageCmsProfile): @@ -740,25 +748,26 @@ def getProfileModel(profile): except (AttributeError, IOError, TypeError, ValueError) as v: raise PyCMSError(v) -## -# (pyCMS) Gets the description 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 description tag, a PyCMSError -# is raised -# -# Use this function to obtain the information stored in the profile's -# description tag. -# -# @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 getProfileDescription(profile): + """ + (pyCMS) Gets the description 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 description tag, a PyCMSError + is raised + + Use this function to obtain the information stored in the profile's + description tag. + + :param profile: EITHER a valid CmsProfile object, OR a string of the filename + of an ICC profile. + :returns: A string containing the internal profile information stored in an ICC + tag. + :exception PyCMSError: + """ + try: # add an extra newline to preserve pyCMS compatibility if not isinstance(profile, ImageCmsProfile): @@ -768,35 +777,35 @@ def getProfileDescription(profile): raise PyCMSError(v) - -## -# (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): + """ + (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. + :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. + :exception PyCMSError: + """ + try: if not isinstance(profile, ImageCmsProfile): profile = ImageCmsProfile(profile) @@ -804,42 +813,43 @@ def getDefaultIntent(profile): except (AttributeError, IOError, TypeError, ValueError) as v: raise PyCMSError(v) -## -# (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): + """ + (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) + + :returns: 1 if the intent/direction are supported, -1 if they are not. + :exception PyCMSError: + """ + try: if not isinstance(profile, ImageCmsProfile): profile = ImageCmsProfile(profile) @@ -852,10 +862,11 @@ def isIntentSupported(profile, intent, direction): except (AttributeError, IOError, TypeError, ValueError) as v: raise PyCMSError(v) -## -# (pyCMS) Fetches versions. - def versions(): + """ + (pyCMS) Fetches versions. + """ + import sys return ( VERSION, core.littlecms_version, sys.version.split()[0], Image.VERSION