PIL（Python Imaging Library）官方文档翻译 The Image Module

渣翻，仅供参考，如有错误，欢迎指正

原文：http://effbot.org/imagingbook/image.htm#tag-Image.Image.draft

  

#函数：
image = Image.new(mode,size,color)  
#建立一个新的图像，mode表示色彩空间;size表示大小;color表示初始颜色,缺省时为黑色。如果color为None，则图片不会初始化，以便于画图或复制图片。


image = Image.open(file,mode)  
#打开一个图像，file是文件地址，mode可以缺省，但存在时必须为r。在image被处理前图片都不会被加载（如果想强制加载，请用load模型）


image = Image.blend(image1,image2,alpha)   
#建立一个介于image1和image2的插值图片其结果为：
#out = image1 * (1.0 - alpha) + image2 * alpha
#当alpha为0时，out = image1
#当alpha为1时，out = image2


image = Image.composite(image1,image2,mask)  
#建立一个插值图片（类比blend方法）其中每个像素将mask中的像素视作alpha进行计算，mask可以是’1‘，’L'或是‘RGBA'形式的图片。所有的图片必须是同样的大小。


image = Image.eval(imabe,function)  
#将函数（function)应用到所提供图片的所有像素上。如果图像有多个通道，则函数会应用到每一个通道上。


image = frombuffer(mode,size,data)  
#用’raw‘解码器，以一个字符串或是缓存对象中包含的像素数据建立一个图片内存（空间），对于某些模式，图片将与原始的缓存共享内存（对原始的缓存对象的改变也会反映到锁生成的图片中）支持共享内存的mode包括"L","RGBX","RGBA",和"CMYK".对与其他的mode，此函数与fromstring函数表现（功能）相同。
#Note: In versions up to and including 1.1.6, the default orientation differs from that of fromstring. This may be changed in future versions, so for maximum portability, it’s recommended that you spell out all arguments when using the “raw” decoder:
#im = Image.frombuffer(mode, size, data, "raw", mode ,0 , 1)


image = Image.frombuffer(mode, size, data, "raw", mode, 0, 1)
image = Image.fromstring(mode,size,data)
#用标准的”raw“解码器，以一个字符串多包含的像素数据建立一个图片内存


image = Image.fromstring(mode,size,data,decode,parameters)
#同上，但是允许你用任何PIL支持的像素解码器
#注意这个函数只解码像素数据而不是整幅图片，如果你有在字符串中存储了整幅图片，请把他变成StringIO对象，并使用open函数加载他。


image = Image.merge(mode,bands)
#以一个但通道图片建立一个新的图片。bands应提供一个元组(tuple)或列表(list)的图片，one for each band described by the mode.所有的通道都必须有同样的大小。


#方法
#所有Image类都有下列方法。除非另有陈述，所有方法返回一个新的Image类，并包含结果图片。


image = im.convert(mode)
#将im转化成其他类别的图片，并返回一个新的图片。
#当用来转化一个彩色（palette，调色板）图片，this translates pixels through the palette. If mode is omitted, a mode is chosen so that all information in the image and the palette can be represented without a palette.
#当用来转化彩色图片到灰度图片，该方法使用ITU-R 601-2 luna 转化：
#      L = R *299/1000 + G *587/1000 + B *114/1000
#当要转化为二值图片时，源图片先转化为灰度图片。结果中像素的值大于127的会被设为白色（1），然后图像将会颤抖（dithered，实测为图像会有颗粒感），若想使用其他阈值，请使用point方法。若想消除颤抖（dithered),使用dither=option(详情请往下看）


image = im.convert("P",**options)
#同上，但是在将"RGB"图片转化为8位彩色图片时会提供更好的控制。可使用的options有:
#dither=. 控制颤抖（dithering）。默认为FLOYDSTEINBERG,这回将错误分散到临近的像素上。为了消除颤抖，使用NONE。
#palette=.控制调色板生成器。默认为WEB，216-color”网页调色板。要使用最优调色板，使用ADAPTIVE.
#colors=.当palette是ADAPTIVE时，控制调色板所使用的颜色数量。默认为最大值，256 colors。


image = im.convert(mode,matrix)
#将"RGB"图片转化为"L"（灰度）图片或使用一个转化矩阵来转化"RGB"图像。矩阵是一个4维或16维维的元组。
#下列例子将RGB图像转化到CIE XYZ颜色空间：
#Convert RGB to XYZ
  rgb2xyz = (
    0.412453, 0.357580, 0.180423, 0,
    0.212671, 0.715160, 0.072169, 0,
    0.019334, 0.119193, 0.950227, 0 )
  out = im.convert("RGB",rgb2xyz)


image = im.copy()
#复制图片。如果你想复制图片到一个图片并保留原图，就使用此方法。（猜测与存储方式有关，例如改变原图是否会影响到新复制的图片，未测试，未证实）


image = im.crop(box)
#返回一个从原图上的一个正方形区域的复制。box是一个4维元组，定义了左，上，右和下的像素候选区（其实就是左上和右下的坐标，坐标原点在左上角）。
#这是一个懒操作(lazy operation,快去干活！).改变源图片可能，也可能不反映到（改变）切割下来的图片。若想要获得一个分离的复制品 (copy)，则调用剪切下来的复制品的load方法。


image = draft(mode,size)
#设定图片加载器，使其返回尽可能与mode和size相符的图片版本。例如你可以在加载图片的时候用此方法将JPEG图片转化为灰度图片，或是从一个PCD文件中提取一个128x192版本。
#注意此方法在适当的地方修改图片对象（更准确的说，它重置了文件阅读器）。如果图片已经被加载，此方法就没有效果了。


image = im.filter(filter)
#返回一个经过所提供的filter改变过的图片的复制品。一系列filter请看：
#http://effbot.org/imagingbook/imagefilter.htm


image = im.fromstring(data)
image = fromstring(data,decoder,parameters)
#与fromstring函数相同，但是加载当前图像的图像。


tuple_of_strings = im.getbands()
#返回包含通道名称的元组。例如，RGB图像使用getbands会返回(“R”,”G”,”B”)


im.getbbox() ⇒ 4维tuple or None
#计算图像中非零区域的bounding box。bounding box 以4维元组的形式当做返回值，其中包含左，上，右和下的像素候选区（其实就是左上和右下的坐标，坐标原点在左上角）。如果图像时全空的，此方法返回None。


im.getcolors() ⇒ a list of (count, color) tuples or None
im.getcolors(maxcolors) ⇒ a list of (count, color) tuples or None
#返回一列未排序的，包含（count，color）元组的列表，其中，count表示图片中颜色color出现的次数。
#如果（颜色）超过了maxcolors的值，此方法将停止计数并返回None。默认的maxcolors的值为256。为了确保你可以得到图片中的所有颜色，你可以置入size[0]*size[1]（但是在将此方法应用在巨大的图片前，请确保你有足够的内存）


sequence = im.getdata()
#返回一个包含图像像素值的数列。这个数列是一维的，所以第一行的值紧跟着第0行的值，后面以此类推。
#注意由此方法返回的数列对象时PIL内部的数据类型，他只支持特定的数列操作，包括迭代和基本的数列处理。若想把它转化成一般的数列（例如想要把它显示出来），用list(im.getdata())。


im.getextrema() ⇒ 2维tuple
#返回一包含图像像素值中最大值和最小值的2维元组。在当前PIL的版本中，此方法只适用于单通道图像。


value_or_tuple = im.getpixel(xy)
#返回在xy处的像素值。如果图像是一个多层（多通道）图像，此方法返回一个元组。
#注意此方法很慢，如果你需要处理图片上大一些的区域，你可以使用像素处理对象，或是getdata方法。


list = im.histogram()
#返回一个图像的直方图。直方图以像素数量列表的形式返回，每一项都代表一个像素值在原图像中的数量。如果图像有不知一个通道，直方图会把所有通道联系起来。（例如”RGB”图片的直方图有768个值）。
#一个二值图片（mode ‘1’）在此方法中会被看做是灰度（“L”）图像。


list =im. histogram(mask)
#返回一个在mask非零部分所覆盖区域的直方图。mask图像必须与原图像具有相同的尺寸，并且是灰度或是二值图片之一。


im.load()
#为图片分配内存，并将其从文件中（或是为了懒操作，从源中（or from the source, for lazy operations））加载，你不需要主动使用此方法，在图像第一次被处理时，这个被打开的图片会被自动加载。


#在1.1.6或往后的版本中。load返回一个可以用来读取和修改像素的像素处理对象。这个处理对象表现得像一个二维数组一样，所以你可以这样操作：
pix = im.load()
print pix[x, y]
pix[x, y] = value
通过这个对象的处理过程要比getpixel和putpixel快的多


image = im.offset(xoffset,yoffset)（经测试，该方法已被移除，请用ImageChops.offset）


im.paste(image,box)
#将其他的图片粘贴到这张图片上。这个box参数是一个提供上左角的2元组，或是一个提供左，上，右，下的4维元组候选区，或是空（None或者（0,0））如果提供了4维元组，被粘贴的图片必须与这个元组所确定的的区域的尺寸相符。


#如果两张图片的模式（RGB,灰度，位图）不同，被粘贴的图片将转化成本图片的模式(详情参考convert方法)。


im.paste(colour,box)
#同上，但是在相应区域填充单一颜色。在im是单通道图片时，color为单个数值，而当im是多通道图片时，color是一个元组。
im.paste(image,box,mask)
#同上，但是只更新被mask所指明的区域。你可以使用”1”,”L”,”RGBA”(分别是位图，灰度，RGB)图片（在后者，第一个通道（alpha band）被用作mask）。mask上的值为255的地方，按照被选图片（image）复制。mask上的值为0的地方，保留原图。mask上的中间值可以视为透明效果。
#注意如果你粘贴一个“RGBA”图片，第一个通道（alpha）通道会被忽略。你可以把这个图片同时当做源图片或是mask。


im.paste(colour,box,mask)
同上，但是在mask所指明的区域填充单色


image = im.point(table)
image = im.point(function)
#返回原图片的复制，其每个像素都遍历过table。table在图片中的每个通道都有256个值。如果使用的是function(函数)，应当输入单一参数。函数会在每个可能的项所上都调用一次。并且结果表格（table）会应用到图片的每一个通道上。
#如果图片是“I”(整型)或“F”（浮点型）模式，你必须使用函数，并且函数必须有如下形式：
#     argument * scale + offset
#     变量 * 幅值 + 补偿
#例:
#     out = im.point(lambda i: i * 1.2 + 10)
#你可以省略幅值或是补偿


image = im.point(table,mode)
image = im.point(function,mode)
#同上，但是为输出图像指定一个新的模式。这可以将‘L’或是‘P’模式的图像直接转化为‘1’模式，例：按阈值分割图片。
（1.1.5版本开始）使用这种形式同样可以将’L’图像转化为‘I’或者‘F’，并且可以将‘I’图像以16位的形式转化为‘L’，在第二种情况，你必须使用一个65536项的查找表格。
im.putalpha(band)
#将所提供的通道（band）复制到图像的alpha layer
#图像必须是“RGBA”图像，并且通道的模式必须是“L”或是“1”


#（1.1.5之后）你在其他模式上也可以使用putalpha；图像会被直接转换成具有alpha layer的常用的模式（通常是“LA”或者“RGBA”）。并且，参数band可以是一个图像，或者一个颜色值（整数）。


im.putdata(data)
im.putdata(data,scale,offset)
#从左上角（0,0）开始，复制一个数列对象上的像素值到图片。其中scale和offset的值被用来调整数列的值：
# pixel = value * scale + offset
#scale缺省值为1.0，offset缺省值为0.0
im.putpalette(sequence)
#给一个“P”或者“L”图像联系一个调色板（黑白图像上色？）。对于“L”图片，模式将被转化为“P”。调色板数列（sequence）应当包含768整数值，每组的三个值分别代表相对应的红，绿，蓝三色。你可以使用768位字符串代替整数数列。


im.putpixel(xy,colour)
#修正给定位置的像素。对于一个单通道图片，colour应为一个单一数值；对于一个多通道图片，colour是一个元组。
#注意这个方式相对较慢，如果你使用1.16，像素处理对象提供一个更快的修复图像的方法。若果你洗那个生成整幅图片，生成一个Python列表（list）并用putdata来将其复制到图像上会更有效。如果想要更大尺度的改变，请使用paste或者ImageDraw模块。
#你可以以直接调用内部putpixel方法来稍微加快putpixel处理速度：
    im.load()
    putpixel = im.im.putpixel
    for i in range(n):
     …
     putpixel((x, y), value)
#在1.1.6中，上述代码最好写为：
   pix = im.load()
   for I in range(n):
…
pix[x, y] = value


image = im.quantize(colors ,**options)
#(不建议)按照给定数量的colors，将“L”图片或者“RGB”图片转化为“P”图片，并返回一个新的图片。
#对于新的代码，请使用带有最适化色盘的convert方法
out = im.convert(“P”,palette=Image.ADAPTIVE， colors=256)


image = im.resize(size)
image = im.resize(size, filter)
#返回一个调整过大小的图片的复制品。size参数给出一个，以像素为单位的二维元组（weight, height）
#参数filter可以是NEAREST（使用临近取样）,BILINEAR（在2x2环境中的线性插值），BICUBIC（在4x4环境下的三次样条插值），或者ANTIALIAS（一个高质量的下采样过滤器），如果缺省，或图像的模式为“1”或者“P”，它将被设置为NEAREST。
#注意在最新版本的PIL中，双线性和三次样条过滤器并不是非常适合较大的下采样率（例如制作缩略图）你应当使用ANTIALLAS除非速度比质量更重要。


image = im.rotate(angle)
image = im.rotate(angle, filter=NEAREST, expand=0)
#注意expand等号后面是零，不是英文o
#返回一个围绕图片中心顺时针旋转angle度的图片的复制品。
#参数filter可以是NEAREST（使用临近取样）,BILINEAR（在2x2环境中的线性插值），或者BICUBIC（在4x4环境下的三次样条插值，如果缺省，或图像的模式为“1”或者“P”，它将被设置为NEAREST。
#如果参数expand为真，表示输出图片应该足够大来装下旋转过的图片。其缺省值为假，输出图片与输入有一样的尺寸。


im.save(outfile,options…)
im.save(outfile,format,options…)
#以给定的文件名保存图片。如果格式（format）被忽略，格式由文件名的扩展名决定，如果可能，此方法返回None。
#键盘选项（Keyword options）可以被用为作者提供额外的知道。如果作者并不认识这个选项，它会被忽略。可用的选项会在本手册的后面为您介绍。
#你可以使用一个文件对象来代替文件名。在这个情况下，你必须明确格式。文件对象必须使用seek,tell和write方法，并以2进制模式打开。
#如果由于某种原因，保存失败此方法会提示一个异常（通常是一个IOError异常）。如果这种情况发生了，此方法可能已经建立文件并在其中写入数据。如果需要的话，你的程序可以视情况删除未完成的文件。


im.seek(frame)
#在一个队列文件中寻找给定的frame。如果你的寻找过过程超出了队列的末尾，此方法会提示一个EOFError异常。当一个队列文件被打开，此库会自动寻找到frame 0（零）。
#注意在最新版本的库中，大多数队列格式只允许你寻找下一个frame。


im.show()
#展示一个图片。此方法主要用于检查错误。
#在Unix平台上，此方法将图片保存到一个临时的PPM文件，并且调用xv 程序
#在Windows系统上，此方法将图片保存到一个临时的BMP文件，并使用标准的BMP显示程序来展示它。
#此方法返回空。


sequence = im.split()
#返回一个包含图片独立通道的元组。例如，分离一个“RGB”图像会创建三个新的，包含每个原始通道（红，绿，蓝）复制品的图片。


integer = im.tell()
#返回一个最新的frame数字


im.thumbnail(size)
im.thumbnail(size,filter)
#修改图片使其包含一个比给定size小的自己的缩略图。此方法计算一个适当的缩略图大小的来保存此图片的面貌，调用draft方法来配置文件阅读器（适用时），并最终调整图片的大小。
#filter参数可以是NEAREST, BILINEAR, BICUBIC, or ANTIALIAS（效果最好）之一，如果缺省，则默认为NEAREST。
#注意在最新版本的PIL中，双线性和三次样条过滤器并不是非常适合缩略图的生成。你应当使用ANTIALLAS除非速度比质量更重要。
#同样注意，这个方法会在原图上修改。如果你同样需要使用全分辨率的原图片，请在原图的复制品（例如用copy方法）上使用此方法。此方法返回空。


string = im.tobimap()
#返回转化成X11 位图的图片


string = im.tostring()
#返回一个包含像素数据的字符串，使用标准“raw”译码器


string = im.tostring(encoder, parameters)
#返回一个包含像素数据的字符串，使用给定的数据编码（方式）。
#注意：tostring方法只接受原始像素数据。若要将图片以一个标准文件格式保存到一个字符串上，给save方法设置（pass）一个StringIO对象（或者相当的）。


image = im.transform(size, method, data)
image = im.transform(size, methon, data, filter)
#按照给定尺寸（size），给定的转变方式，与原图片相同的模式和数据创建一个新的图片。
#在最新版本的PIL中，method参数可以是 EXTENT (切下一块矩形区域), AFFINE (仿射变换), QUAD (将四边形扩展成矩形), MESH (map a number of source quadrilaterals in one operation), or PERSPECTIVE. 这多种方法在下面详细描述。
#filter参数定义如何从源图片上过滤像素。在最新的版本中，它可以是NEAREST (临近取样), BILINEAR(在2x2环境下的线性插值), or BICUBIC (在4x4环境下的三次样条插值). 若果缺省, 或图像的模式为“1”或者“P”, 它会被设为NEAREST.


image = im.transform(size, EXTENT, data)
image = im.transform(size, EXTENT, data, filter)
#从愿图片上提取一块区域。
#Data 是一个四维元组（x0,y0,x1,y1）,它确定了在数日图像候选区系统上的亮点。结果图片将包含从两点间取样来的数据，例如输入图像的(x0, y0)点会结束于输出图像的(0,0)
而(x1,y1)对应于size的位置。
这个方法而已用于剪切，拉伸，收缩或镜像一个任意最近图像上的矩形。它比crop方法稍微慢一些，但是与resize操作差不多快。


image = im.transform(size, AFFINE, data)
image = im.transform(size, AFFINE, data, filter)
#对图片使用一个仿射变换，并将结果放置在一个有着给定尺寸（size）的新图片中。
#数据是一个6维元组(a,b,c,d,e,f,),它包含仿射变换矩阵的前两行。对于输出图片中的每一个(x,y),新的值是从输入函数的位置(a x + b y + c, d x + e y + f)中取出的，舍入到最近的像素（rounded to neared pixel）。
#这个函数可以被用于改变比例，转化，旋转和剪切原图片。


image = im.transform(size, QUAD, data)
image = im.transform(size, QUAD, data, filter)
#从原图取一个四边形（由四个角所定义的区域）绘制到到一个给定大小的矩形中。
#data是一个8维元组(x0,y0,x1,y1,x2,y2,x3,y3),它包含源四边形的了上左，下左，下右，上右四个角。


image = im.transform(size, MESH, data)
image = im.transform(size, MESH, data, filter)
#与QUAD类似，但是data是一个列表(lst)的目标矩形或是相应的源四边形


image = im.transform(size, PERSPECTIVE, data)
image = im.transform(size, PERSPECTIVE, filter)
#对图片使用透视变换，并将结果放置在给定大小的新图片中
#数据是一个8维元组(a,b,c,d,e,f,g,h),它包含一个透视变化所需的系数。对于输出图片的每个像素(x,y)，新的值由原图片在(a x + b y + c)/(g x + h y + 1), (d x + e y + f)/(g x + h y + 1)取得 ，舍入到最近的像素（rounded to neared pixel）。
#这个函数被用来改变原图片的2维透视。


image = im.transpose(method)
#返回一个翻转或旋转的图片的复制品
#method可以是下列之一: FLIP_LEFT_RIGHT,FLIP_TOP_BOTTOM, ROTATE_90, ROTATE_180, or ROTATE_270。


im.vertify()
#尝试不用解码图片数据确定文件是否损坏。如果这个方法发现了任何问题，它会提示合适的异常。这个方法只在最近打开的图片上有效；如果图像已经被加载，结果是未定义的。因此如果你需要在加载这个图片后是用这方法，你必须重新打开图片文件。
#注意这个方法并不能发现所有可能错误；若想发现解码错误，你可能还需加载整幅图片。


#属性


#Image类有如下属性：


string_or_None = im.format
#源文件的文件格式。对于由库创建的格式（通过一个函数（factory function），或是用已存在的图片的方法）这个属性设为空。


string = im.mode
#图像模式，这是一个字符串解释这幅图片中的像素格式。典型的值为“1”，“L”，“RGB”，或者“CMYK”详情请见Concept。


(width, height) = im.size
#图像的尺寸，以像素为单位。尺寸以一个2维元组(width, height)的形式返回


platte_or_None = im.palette
#颜色调色板表，如果有的话。如果模式是“P”，请参考ImagePalette类。否则将被置为空。


dictionary = im.info
#一个包含图片相关数据的字典。这个字典被文件处理器用来pass多种从图片中阅读的非图片信息。请看关于多种文件处理器的文档以获得更多细节。
#大多是方法再返回一个新的图片的时候回忽视字典；自从keys并未标准化，对于一个方法知道它的操作是否会影响字典是不可能的。如果你需要相关信息，请注意由open方法返回的info字典。