对象存储
文档捉虫大赛：人工智能与机器学习专题> HOT
文档中心 > 对象存储 > API 文档 > 数据处理接口 > 图片处理 > 基础图片处理 > 裁剪

裁剪

最近更新时间：2023-04-20 09:51:04

我的收藏

本页目录：

功能概述

对象存储通过数据万象接口 imageMogr2 提供裁剪功能，包括普通裁剪、缩放裁剪、内切圆裁剪、圆角裁剪和人脸智能裁剪。
该功能支持以下处理方式：
下载时处理
上传时处理
云上数据处理
注意
图片处理功能为收费项，由数据万象收取，详细的计费说明请参见数据万象 图片处理费用。

限制说明

支持格式：支持处理 JPG、BMP、GIF、PNG、WebP 格式，并且支持 HEIF 格式的解码和处理操作。
静图体积限制：处理图片原图大小不超过32MB、宽高不超过50000像素且总像素不超过2.5亿像素，处理结果图宽高设置不超过9999像素。
WebP图片限制：处理图片原图大小不超过32MB、宽高不超过16383像素且总像素不超过2.5亿像素，处理结果图宽高设置不超过16383像素。
动图体积限制：原图及处理图宽 x 高 x 帧数不超过2.5亿像素。
动图帧数限制：gif 帧数限300帧。

接口示例

1. 下载时处理

GET /<ObjectKey>?imageMogr2/cut/<width>x<height>x<dx>x<dy>
                       /crop/<imageSizeAndOffsetGeometry>
                       /iradius/<radius>
                       /rradius/<radius>
                       /scrop/<Width>x<Height> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>
说明
请忽略上面的空格与换行符。

2. 上传时处理

PUT /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Authorization: Auth String
Pic-Operations: 
{
  "is_pic_info": 1,
  "rules": [{
      "fileid": "exampleobject",
      "rule": "imageMogr2/cut/<width>x<height>x<dx>x<dy>
                       /crop/<imageSizeAndOffsetGeometry>
                       /iradius/<radius>
                       /rradius/<radius>
                       /scrop/<Width>x<Height>"
  }]
}

3. 云上数据处理

POST /<ObjectKey>?image_process HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-length: Size
Authorization: Auth String
Pic-Operations: 
{
  "is_pic_info": 1,
  "rules": [{
      "fileid": "exampleobject",
      "rule": "imageMogr2/cut/<width>x<height>x<dx>x<dy>
                       /crop/<imageSizeAndOffsetGeometry>
                       /iradius/<radius>
                       /rradius/<radius>
                       /scrop/<Width>x<Height>"
  }]
}
说明
Authorization: Auth String（详情请参见 请求签名 文档）。
通过子账号使用时，需要授予相关的权限，详情请参见 授权粒度详情 文档。
Pic-Operations 为 json 格式的字符串，具体参数信息可参考 图片持久化处理。
当 fileid 与 ObjectKey 相同时，处理后的图片将覆盖原图存储；不相同时将分别存储原图和处理后图片。
fileid 的值需要经过 URL 安全的 Base64 编码。


处理参数说明

参数
含义
ObjectKey
对象文件名，例如 folder/sample.jpg。
/ignore-error/1
当处理参数中携带此参数时，针对文件过大导致处理失败的场景，会直接返回原图而不报错

普通裁剪参数说明

操作名称：cut。
参数
含义
<width>
指定目标图片的宽为 width
<height>
指定目标图片的高为 height
<dx>
相对于图片左上顶点水平向右偏移 dx
<dy>
相对于图片左上顶点水平向下偏移 dy
说明
参数取值范围应大于0，小于原图宽高。

缩放裁剪参数说明

操作名称：crop。
参数
含义
/crop/<Width>x
指定目标图片宽度为 Width，高度不变。Width 取值范围应大于0，小于原图宽度
/crop/x<Height>
指定目标图片高度为 Height，宽度不变。Height 取值范围应大于0，小于原图高度
/crop/<Width>x<Height>
指定目标图片宽度为 Width，高度为 Height 。Width 和 Height 取值范围都应大于0，小于原图宽度/高度
在进行缩放裁剪操作时，您也可以使用 gravity 参数指定操作的起点位置，详见下文中 缩放裁剪操作示例。

内切圆裁剪参数说明

操作名称：iradius。
参数
含义
/iradius/<radius>
内切圆裁剪功能，radius 是内切圆的半径，取值范围为大于0且小于原图最小边一半的整数。内切圆的圆心为图片的中心。图片格式为 gif 时，不支持该参数。
处理后图片如果是PNG、WebP或BMP等支持透明通道的图片，那么图片非圆形区域的部分将会以透明填充；如果是JPG图片，不支持透明通道，非圆形区域是以白色进行填充。

圆角裁剪参数说明

操作名称：rradius。
参数
含义
/rradius/<radius>
圆角裁剪功能，radius 为图片圆角边缘的半径，取值范围为大于0且小于原图最小边一半的整数。圆角与原图边缘相切。图片格式为 gif 时，不支持该参数。
处理后图片如果是PNG、WebP或BMP等支持透明通道的图片，那么图片非圆形区域的部分将会以透明填充；如果是JPG图片，不支持透明通道，非圆形区域是以白色进行填充。

人脸智能裁剪参数说明

操作名称：scrop。
参数
含义
/scrop/<Width>x<Height>
基于图片中的人脸位置进行缩放裁剪。目标图片的宽度为 Width、高度为 Height。

九宫格方位图

九宫格方位图可为图片的多种操作提供位置参考。红点为各区域位置的原点（通过 gravity 参数选定各区域后位移操作会以相应远点为参照）。


注意
当 gravity 参数设置为 center 时，dx、dy 参数无效。
当 gravity 参数设置为 north 或 south 时，dx 参数无效（水印会水平居中）。
当 gravity 参数设置为 west 或 east 时，dy 参数无效（水印会垂直居中）。

实际案例

说明
本篇文档中的实际案例仅包含下载时处理，该类处理不会保存处理后的图片至存储桶。如有保存需求，您可查阅 图片持久化处理 文档并配置上传时处理或云上数据处理。

案例一：普通裁剪

相对于图片左上顶点水平向右平移100像素，垂直向下平移10像素，指定目标图片大小为600×600进行裁剪：
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?imageMogr2/cut/600x600x100x10
原图如下：


最终效果如下：



案例二：缩放裁剪

假设以中心点 center 为参考点，缩放裁剪至300×400，示例如下：
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?imageMogr2/crop/300x400/gravity/center
最终效果如下：



案例三：内切圆裁剪

取半径为200，进行内切圆裁剪：
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?imageMogr2/iradius/200
最终效果如下：



案例四：圆角裁剪

取半径为100，进行圆角裁剪：
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?imageMogr2/rradius/100
最终效果如下：



案例五：人脸智能裁剪

基于图片中的人脸位置进行缩放裁剪，目标图片大小为100×600，示例如下：
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?imageMogr2/scrop/100x600
说明
如果图片中没有识别到人脸，则返回原图。

案例六：人脸智能裁剪并携带私有文件签名

处理方式同上，仅增加签名部分，并与图片处理参数以“&”连接，示例如下：
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?q-sign-algorithm=<signature>&imageMogr2/scrop/100x600
说明
<signature>为签名部分，获取方式请参考 请求签名。

注意事项

为了避免未授权人员通过访问不携带处理参数的链接实现访问和下载原图的情况，您可同时将处理参数签入到请求签名中，处理参数整体是参数的 key，value 为空，如下是简单的示例（仅做样式参考，可能已经过期无法直接访问），详细计算方法请参见 请求签名。
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?q-sign-algorithm=sha1&q-ak=AKID********************&q-sign-time=1593342360;1593342720&q-key-time=1593342360;1593342720&q-header-list=&q-url-param-list=watermark%252f1%252fimage%252fahr0cdovl2v4yw1wbgvzlteyntewmdawmdqucgljc2gubxlxy2xvdwquy29tl3nodwl5aw4uanbn%252fgravity%252fsoutheast&q-signature=26a429871963375c88081ef60247c5746e834a98&watermark/1/image/aHR0cDovL2V4YW1wbGVzLTEyNTEwMDAwMDQucGljc2gubXlxY2xvdWQuY29tL3NodWl5aW4uanBn/gravity/southeast

中国站