智能多媒体 API

  • 图片高级处理

    最近更新时间:2017-08-28 01:39:33

    imageMogr2 提供一系列高级图片处理功能,包括格式转换、缩放、裁剪、旋转等。imageMogr2 接口可支持处理的原图片格式有 psdjpegpnggifwebptiffbmp
    注意:imageMogr2 接口支持的最大 gif 帧数为 200,超过 200,处理结果只返回原图。

    接口规格

    注意:接口规格不含任何空格与换行符。

    imageMogr2/auto-orient
              /thumbnail/<imageSizeGeometry>
              /strip
              /gravity/<gravityType>
              /crop/<imageSizeAndOffsetGeometry>
              /rotate/<rotateDegree>
              /format/<destinationImageFormat>
              /blur/<radius>x<sigma>
              /interlace/<Interlace>
              /quality/<quality>
              /sharpen/<sharpen>
              /size-limit/<sizeLimit>
    
    参数名称 必填 说明
    auto-orient 建议放在首位,根据原图EXIF信息自动旋正,便于后续处理。
    thumbnail 参看缩放操作参数表,默认为不缩放。
    strip 去除图片中的元信息。去除的信息有:bKGD、cHRM、EXIF、gAMA、iCCP、iTXt、sRGB、tEXt、zCCP、zTXt、date
    gravity 参看图片处理重心参数表,目前在imageMogr2中只影响其后的裁剪偏移参数,默认为左上角(NorthWest)。
    crop 参看裁剪操作参数表,默认为不裁剪。
    rotate 旋转角度,取值范围为1-360,默认为不旋转。
    format 图片格式。支持jpg、gif、png、webp等,默认为原图格式,参看支持转换的图片格式
    blur 高斯模糊参数。radius是模糊半径,取值范围为1-50。sigma是正态分布的标准差,必须大于0。图片格式为gif时,不支持该参数。
    interlace 是否支持渐进显示。取值1支持渐进显示,取值0不支持渐进显示(默认为0)。适用jpg目标格式,网速慢时,图片显示由模糊到清晰。
    quality 新图的图片质量。取值范围为1-100,默认75。七牛会根据原图质量算出一个修正值,取修正值和指定值中的小值。


    注意:
    ● 如果图片的质量值本身大于90,会根据指定值进行处理,此时修正值会失效。
    ● 指定值后面可以增加 !,表示强制使用指定值,如:100!
    ● 支持图片类型:jpg。

    sharpen 图片是否锐化,当设置值为1时打开锐化效果。
    size-limit 限制图片转换后的大小,支持以兆字节和千字节为单位的图片。

    ● 仅对于jpg格式的图片,可以用于限制图片转换后的大小,支持魔法变量$(fsize)表示原图大小。如:http://developer.qiniu.com/resource/Ship.jpg?imageMogr2/size-limit/$(fsize)


    ● 对于所有图片格式,若在尾部加上!,表示用转换后的图片大小与原图大小做比较,如果转换后的图片比原图小,则返回转换后的图片,否则返回原图。如:http://developer.qiniu.com/resource/Ship.jpg?imageMogr2/size-limit/15k!。这个主要用于保证返回的图片不会比原图大。


    注意:需要根据图片实际大小设置合理的sizeLimit大小。

    quality 修正值算法:min [ 90,原图 quality * sqrt ( 原图长宽乘积 / 结果图片长宽乘积 ) ]

    注意:

    • 处理后的图片wh参数不能超过9999像素,总像素不得超过24999999(2500w-1)像素。
    • 处理前的图片wh参数不能超过3万像素,总像素不能超过1.5亿像素。

    缩放操作参数表

    参数名称 必填 说明
    /thumbnail/!<Scale>p 基于原图大小,按指定百分比缩放。Scale取值范围1-999。
    /thumbnail/!<Scale>px 以百分比形式指定目标图片宽度,高度不变。Scale取值范围1-999。
    /thumbnail/!x<Scale>p 以百分比形式指定目标图片高度,宽度不变。Scale取值范围1-999。
    /thumbnail/<Width>x 指定目标图片宽度,高度等比缩放,Width取值范围1-9999。
    /thumbnail/x<Height> 指定目标图片高度,宽度等比缩放,Height取值范围1-9999。
    /thumbnail/<Width>x<Height> 等比缩放,比例值为宽缩放比和高缩放比的较小值,Width 和 Height 取值范围1-9999。


    注意:宽缩放比:目标宽/原图宽   高缩放比:目标高/原图高

    /thumbnail/!<Width>x<Height>r 等比缩放,比例值为宽缩放比和高缩放比的较大值,Width 和 Height 取值范围1-9999。


    注意:宽缩放比:目标宽/原图宽   高缩放比:目标高/原图高

    /thumbnail/<Width>x<Height>! 按指定宽高值强行缩略,可能导致目标图片变形,width和height取值范围1-9999。
    /thumbnail/<Width>x<Height>> 等比缩小,比例值为宽缩放比和高缩放比的较小值。如果目标宽和高都大于原图宽和高,则不变,Width 和 Height 取值范围1-9999。


    注意:宽缩放比:目标宽/原图宽   高缩放比:目标高/原图高;

    /thumbnail/<Width>x<Height>< 等比放大,比例值为宽缩放比和高缩放比的较小值。如果目标宽(高)小于原图宽(高),则不变,Width 和 Height 取值范围1-9999。


    注意: 宽缩放比:目标宽/原图宽   高缩放比:目标高/原图高;

    /thumbnail/<Area>@ 按原图高宽比例等比缩放,缩放后的像素数量不超过指定值,Area取值范围1-24999999。

    注意:

    • 处理后的图片 Width 和 Height 范围1-9999,总像素小于2500万像素。
    • 处理前的图片 Width 和 Height 范围1-29999,总像素不超过 2 亿像素。

    图片处理重心参数表

    在图片高级处理现有的功能中只影响其后的裁剪操作参数表,即裁剪操作以 gravity 为原点开始偏移后,进行裁剪操作。

    NorthWest     |     North      |     NorthEast
                  |                |    
                  |                |    
    --------------+----------------+--------------
                  |                |    
    West          |     Center     |          East 
                  |                |    
    --------------+----------------+--------------
                  |                |    
                  |                |    
    SouthWest     |     South      |     SouthEast
    

    裁剪操作参数表 (cropsize)

    参数名称 必填 说明
    /crop/<Width>x 指定目标图片宽度,高度不变。取值范围为0-10000。
    /crop/x<Height> 指定目标图片高度,宽度不变。取值范围为0-10000。
    /crop/<Width>x<Height> 同时指定目标图片宽高。取值范围为0-10000。

    裁剪偏移参数表 (cropoffset)

    参数名称 必填 说明
    /crop/!{cropsize}a<dx>a<dy> 相对于偏移锚点,向右偏移dx个像素,同时向下偏移dy个像素。取值范围不限,小于原图宽高即可。
    /crop/!{cropsize}-<dx>a<dy> 相对于偏移锚点,从指定宽度中减去dx个像素,同时向下偏移dy个像素。取值范围不限,小于原图宽高即可。
    /crop/!{cropsize}a<dx>-<dy> 相对于偏移锚点,向右偏移dx个像素,同时从指定高度中减去dy个像素。取值范围不限,小于原图宽高即可。
    /crop/!{cropsize}-<dx>-<dy> 相对于偏移锚点,从指定宽度中减去dx个像素,同时从指定高度中减去dy个像素。取值范围不限,小于原图宽高即可。

    示例

    /crop/!300x400a10a10 表示从源图坐标为 x:10,y:10 处截取 300x400 的子图片。
    /crop/!300x400-10a10 表示从源图坐标为 x:0,y:10 处截取 290x400 的子图片。
    注意

    • 必须同时指定横轴偏移和纵轴偏移。
    • 计算偏移值会受到位置偏移指示符 /gravity/ 的影响。默认为相对于左上角 NorthWest 计算偏移值,参考图片处理重心参数表

    转义说明

    部分参数以 ! 开头,表示参数将被转义。为便于阅读,我们采用特殊转义方法,如下所示:

    p => % (percent)
    r => ^ (reverse)
    a => + (add)
    

    即 !50x50r 实际代表 50x50^ 这样一个字符串。而 !50x50 实际代表 50x50 这样一个字符串(该字符串并不需要转义)。\ 中的 OffsetGeometry 部分可以省略,默认为 +0+0。即 /crop/50x50 等价于 /crop/!50x50a0a0,执行 -crop 50x50+0+0 语义。

    请求报文

    请求语法

    GET <imageDownloadURI>?<接口规格> HTTP/1.1
    Host: <imageDownloadHost>
    

    头部信息

    头部名称 必填 说明
    Host 下载服务器域名,可为七牛三级域名或自定义二级域名,参考七牛自定义域名绑定流程

    响应报文

    响应语法

    HTTP/1.1 200 OK
    Content-Type: <imageMimeType>
    
    <imageBinaryData>
    

    头部信息

    头部名称 必填 说明
    Content-Type MIME类型,成功时为图片的MIME类型,失败时为application/json。
    Cache-Control 缓存控制,失败时为no-store,不缓存。

    响应内容

    • 如果请求成功,返回图片的二进制数据。

    • 如果请求失败,返回包含如下内容的 JSON 字符串(已格式化,便于阅读):

    {
        "code":     <HttpCode  int>, 
        "error":   "<ErrMsg    string>",
    }
    
    字段名称 必填 说明
    code HTTP状态码,请参考响应状态码
    error 与HTTP状态码对应的消息文本。

    响应状态码

    HTTP状态码 含义
    200 缩放成功。
    400 请求报文格式错误。
    404 资源不存在。
    599 服务端操作失败。如遇此错误,请将完整错误信息(包括所有的HTTP响应头部)[通过邮件发送][sendBugReportHref]给我们。

    注意

    • imageMogr2 生成的图片会被七牛云存储缓存以加速下载,但不会持久化。需要持久化的缩略图,请参考[持久化数据处理 (pfop)][pfopHref]和[处理结果另存 (saveas)][saveasHref]。

    • auto-orient 参数是和图像处理顺序相关的,一般建议放在首位(根据原图EXIF信息自动旋正)。

    • thumbnail 和 crop 之间的操作可以链式处理,即可以先对图进行缩略再裁剪,或者先裁剪再缩略。

    • gravity 只会使其后的裁剪偏移 cropoffset 受到影响,建议放在 /crop 参数之前。

    • 当处理多帧 gif 图片时,可能处理所需的时间较长并且输出的图片体积较大。如果您有多张多帧 gif 图片需要处理,可在图片上传完成后异步进行预转,这样不必在初次访问时进行图片处理,访问速度更快。请参考[预转持久化处理 (persistentOps)][persistentOpsHref]。

    • 当一张含有透明区域的图片,转换成不支持透明区域的图片格式 jpg、bmp 等时,透明区域填充白色。

    界面操作方式

    通过调试命令参数的方式,对使用者并不方便。我们提供了图片处理的图形化编辑界面,通过以下方式进入:

    1、 登录 七牛控制台,并点击打开 图片处理

    图片处理入口

    2、 选择常用场景,并开始编辑图片处理命令

    图片处理编辑

    实时示例

    缩放

    1. 生成 480x320 缩略图

    等比缩小 75%:

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/thumbnail/!75p
    

    查看效果图

    按原宽度 75% 等比缩小:

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/thumbnail/!75px
    

    查看效果图

    按原高度 75% 等比缩小:

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/thumbnail/!x75p
    

    查看效果图

    2. 生成 700x467 放大图

    指定新宽度为 700px:

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/thumbnail/700x
    

    查看效果图

    指定新高度为 467px:

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/thumbnail/x467
    

    查看效果图

    3. 限定长边,生成不超过 300x300 的缩略图

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/thumbnail/300x300
    

    查看效果图

    4. 限定短边,生成不小于 200x200 的缩略图

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/thumbnail/!200x200r
    

    查看效果图

    5. 强制生成 200x300 的缩略图

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/thumbnail/200x300!
    

    查看效果图

    6. 原图大于指定长宽矩形,按长边自动缩小为 200x133 缩略图

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/thumbnail/200x300>
    

    查看效果图

    7. 原图小于指定长宽矩形,按长边自动拉伸为 700x467 放大图

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/thumbnail/700x600<
    

    查看效果图

    8. 生成图的像素总数小于指定值

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/thumbnail/350000@
    

    查看效果图

    裁剪

    1. 生成 300x427 裁剪图

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/crop/300x
    

    查看效果图

    2. 生成 640x200 裁剪图

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/crop/x200
    

    查看效果图

    3. 生成 300x300 裁剪图

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/crop/300x300
    

    查看效果图

    4. 生成 300x300 裁剪图,偏移距离 30x100

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/crop/!300x300a30a100
    

    查看效果图

    5. 生成 300x200 裁剪图,偏移距离 30x0

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/crop/!300x300a30-100
    

    查看效果图

    6. 生成 270x300 裁剪图,偏移距离 0x100

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/crop/!300x300-30a100
    

    查看效果图

    7. 生成 270x200 裁剪图,偏移距离 0x0

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/crop/!300x300-30-100
    

    查看效果图

    8. 锚点在左上角 (NorthWest),生成 300x300 裁剪图

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/gravity/NorthWest/crop/300x300
    

    查看效果图

    9. 锚点在正上方 (North),生成 300x300 裁剪图

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/gravity/North/crop/300x300
    

    查看效果图

    10. 锚点在右上角 (NorthEast),生成 300x300 裁剪图

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/gravity/NorthEast/crop/300x300
    

    查看效果图

    11. 锚点在正左方 (West),生成 300x300 裁剪图

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/gravity/West/crop/300x300
    

    查看效果图

    12. 锚点在正中 (Center),生成 300x300 裁剪图

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/gravity/Center/crop/300x300
    

    查看效果图

    13. 锚点在正右方 (East),生成 300x300 裁剪图

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/gravity/East/crop/300x300
    

    查看效果图

    14. 锚点在左下角 (SouthWest),生成 300x300 裁剪图

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/gravity/SouthWest/crop/300x300
    

    查看效果图

    15. 锚点在正下方 (South),生成 300x300 裁剪图

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/gravity/South/crop/300x300
    

    查看效果图

    16. 锚点在右下角 (SouthEast),生成 300x300 裁剪图

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/gravity/SouthEast/crop/300x300
    

    查看效果图

    旋转

    顺时针旋转 45 度:

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/rotate/45
    

    查看效果图

    高斯模糊

    半径为 3,Sigma 值为 5:

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/blur/3x5
    

    查看效果图

    渐进显示

    渐进显示图片:

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageMogr2/thumbnail/300x300/interlace/1
    

    查看效果图

    ##保存图片

    可以实时保存图片到指定空间,在上述url的基础上,加上|saveas/encoded(saved_bucket:saved_key)参数。

    1. 原资源是一个名为 Ship.jpg 的图片:

    http://7xvilo.com1.z0.glb.clouddn.com/Ship.jpg
    

    2. 将图片做缩略处理:

    http://7xvilo.com1.z0.glb.clouddn.com/Ship.jpg?imageMogr2/thumbnail/200x200!
    

    3. 对上述云处理结果进行持久化保存:

    #另存操作的目标空间与资源名
    entryURI = "qiniu-developer:Ship-thumb-200x200.jpg"
    
    #编码结果
    encodedEntryURI = "cWluaXUtZGV2ZWxvcGVyOlNoaXAtdGh1bWItMjAweDIwMC5qcGc="
    
    #需要签名的部分
    signingStr = "7xvilo.com1.z0.glb.clouddn.com/Ship.jpg?imageMogr2/thumbnail/200x200!|saveas/cWluaXUtZGV2ZWxvcGVyOlNoaXAtdGh1bWItMjAweDIwMC5qcGc="
    
    #签名算法
    import hmac
    import hashlib
    import base64
    
    str = hmac.new('m6TAzSGQUIU2y5G4F9iLzBh7aDz25rYkj8J....','7xvilo.com1.z0.glb.clouddn.com/Ship.jpg?imageMogr2/thumbnail/200x200!|saveas/cWluaXUtZGV2ZWxvcGVyOlNoaXAtdGh1bWItMjAweDIwMC5qcGc=',hashlib.sha1).digest().encode('base64').rstrip()
    print str
    
    #签名结果
    sign = "bcgojLbLKTsTlhm3XFMYq0cn3lW2G3NAu.....:iRukarshohgP1ZVSOPp2U6nxhok="
    
    ##注意 其中m6TAzSGQUIU2y5G4F9iLzBh7aDz25rYkj8J....指的是sk,bcgojLbLKTsTlhm3XFMYq0cn3lW2G3NAu.....指的是ak,ak,sk在个人面板,密钥管理处获得。
    

    4. 最终得到的完整下载 URL:

    http://7xvilo.com1.z0.glb.clouddn.com/Ship.jpg?imageMogr2/thumbnail/200x200!|saveas/cWluaXUtZGV2ZWxvcGVyOlNoaXAtdGh1bWItMjAweDIwMC5qcGc=/sign/bcgojLbLKTsTlhm3XFMYq0cn3lW2G3NAuJYXZDDf:iRukarshohgP1ZVSOPp2U6nxhok=
    

    5. 保存转码后资源可通过如下 URL 访问:

    http://7xvilo.com1.z0.glb.clouddn.com/Ship-thumb-200x200.jpg
    

    异步实例

    触发持久化

    以Python Sdk为例,本例将空间名为bucket_name中的图片key缩略为长200宽200的图片,并且保存到目标Bucket_Name,且文件名为自定义文件key

    注意: 其他语言 Sdk 可在官方 Sdks 下载,可以通过查看 Sdk 使用指南中触发持久化使用。

    from qiniu import Auth, PersistentFop, build_op, op_save, urlsafe_base64_encode
    
    #对已经上传到七牛的图片发起异步缩略操作
    #access_key,secret_key在个人面板的密钥管理处获得,非个人账号密码
    access_key = '...'
    secret_key = '...'
    q = Auth(access_key, secret_key)
    
    #要缩略的文件所在的空间和文件名。
    bucket_name = '...'
    key = '...'
    
    #pipeline是使用的队列名称,不设置代表不使用私有队列,使用公有队列。
    pipeline = '...'
    
    #要进行缩略的操作。
    fops = 'imageMogr2/thumbnail/200x200!'
    
    #可以对缩略后的文件进行使用saveas参数自定义命名,当然也可以不指定文件会默认命名并保存在当前空间
    saveas_key = urlsafe_base64_encode('目标Bucket_Name:自定义文件key')
    fops = fops+'|saveas/'+saveas_key
    
    pfop = PersistentFop(q, bucket_name, pipeline)
    ops = []
    ops.append(fops)
    ret, info = pfop.execute(key, ops, 1)
    print(info)
    assert ret['persistentId'] is not None
    

    预转持久化

    以Python Sdk为例,本例中将上传的图片缩略为长200宽200的图片,缩略图保存到目标Bucket_Name,且文件名为自定义文件key,原图保存到bucket_name空间,且文件名为key

    注意: 其他语言 Sdk 可在官方 Sdks 下载,可以通过查看 Sdk 使用指南中预转持久化使用。

    from qiniu import Auth, put_file, etag, urlsafe_base64_encode
    import qiniu.config
    
    #access_key,secret_key在个人面板的密钥管理处获得,非个人账号密码
    access_key = '...'
    secret_key = '...'
    
    # 初始化Auth状态
    q = Auth(access_key, secret_key)
    
    # 你要测试的空间, 并且这个文件名key在你空间中存在
    bucket_name = '...'
    key = '...'
    
    # 是使用的队列名称,不设置代表不使用私有队列,使用公有队列。
    pipeline = '...'
    
    # 设置图片缩略参数
    fops = 'imageMogr2/thumbnail/200x200!'
    
    # 通过添加'|saveas'参数,指定处理后的文件保存的bucket和key,不指定默认保存在当前空间,bucket_saved为目标bucket,bucket_saved为目标key
    
    saveas_key = urlsafe_base64_encode('目标Bucket_Name:自定义文件key')#
    
    fops = fops+'|saveas/'+saveas_key
    
    # 在上传策略中指定fobs和pipeline
    policy={
      'persistentOps':fops,
      'persistentPipeline':pipeline
     }
    
    token = q.upload_token(bucket_name, key, 3600, policy)
    
    # 图片所在的本地路径
    localfile = '...'  
    
    ret, info = put_file(token, key, localfile)
    print(info)
    assert ret['key'] == key
    assert ret['hash'] == etag(localfile)
    
    以上内容是否对您有帮助?
  • 提交工单