对象存储图像处理
收藏
我的收藏简介
针对 TOS 内存储的图片文件,用户可以在 GetObject 请求中携带图片处理参数对图片文件进行处理,包括图片缩放、图片裁剪、图片水印、格式转换等。
图片处理特性目前提供 REST API、文件 URL 两种使用方式(管理控制台和 SDK 方式规划中),用户可以随时随地对存储在 TOS 对象存储桶中的图片进行简单的缩放、裁剪、添加水印等操作,并快速获取处理后的图片。
注:处理后的图片会即时返回给用户,不会保存至用户的存储桶中。
图片处理操作方式
用户可以使用以下方式进行图片处理操作。
- 1.REST API:
GET /example.jpg?x-tos-process=image/resize,w_300 HTTP/1.1 Host: endpoint X-Tos-Content-Sha256: sha256 X-Tos-Date: 20220827T132948Z Authorization: authorization
- 2.文件URL:
http://bucket.endpoint/example.jpg?x-tos-process=image/resize,w_300
注:对于私有图片,需要使用 SDK 生成带图片处理参数的预签名 URL 进行操作。
图片处理功能概述
图片处理特性目前支持以下功能,当用户指定多个功能参数时,TOS 将按照参数的顺序依次对图片进行处理。
图片处理 | 参数 | 说明 |
图片缩放 | resize | 将图片缩放至指定大小 |
图片水印 | watermark | 为图片添加图片或文字水印 |
自定义裁剪 | crop | 裁剪指定大小的矩形图片 |
质量变换 | quality | 调整JPG和WebP格式图片的质量 |
格式转换 | format | 转换图片格式 |
获取信息 | info | 获取图片信息,包括基本信息、EXIF信息 |
自适应方向 | auto-orient | 将携带旋转参数的图片进行自适应旋转 |
内切圆 | circle | 以图片中心点为圆心,裁剪出指定大小的圆形图片 |
索引切割 | indexcrop | 按指定x或y轴的大小切分图片,之后选取其中一张图片 |
圆角矩形 | rounded-corners | 按指定圆角大小将图片裁剪成圆角矩形 |
模糊效果 | blur | 对图片进行模糊处理 |
旋转 | rotate | 按指定角度以顺时针方向旋转图片 |
渐进显示 | interlace | 将JPG格式的图片调整为渐进显示 |
获取图片主色调 | average-hue | 获取图片主色调 |
亮度 | bright | 调整图片亮度 |
锐化 | sharpen | 对图片进行锐化处理 |
对比度 | contrast | 调整图片对比度 |
图片处理功能
图片缩放
图片缩放功能(resize)可以对原图大小进行调整。图片缩放功能的参数说明如下所示。
参数说明
参数 | 参数说明 | 取值说明 | 是否必须 |
m | 图片缩放模式 |
| 否 |
w | 目标缩放图宽度 | [1,16384] | 是 |
h | 目标略缩图高度 | [1,16384] | 是 |
l | 目标缩放图长边 | [1,16384] | 是 |
s | 目标缩放图短边 | [1,16384] | 是 |
limit | 指定目标缩放图大于原图时是否进行缩放 |
| 否 |
color | 填充颜色(pad缩放模式时使用) | 十六进制颜色码,取值为000000到FFFFFF,默认值为FFFFFF(白色)。 | 否 |
p | 等比缩放百分比 | [1,1000] 小于100为缩小,大于100为放大(放大需要配合limit参数)。 | 是 |
是否必须:使用 resize 功能,用户必须指定必须参数中的一个,否则报错 MissingArgument。长边:原尺寸与目标尺寸的比值大的边。短边:原尺寸与目标尺寸的比值小的边。
缩放矩形框计算方式以及参数优先级说明
- 1.同时指定w和h参数:使用w和h构造缩放矩形框。
- 2.w和h仅指定其中一个:
- a.lfit、mfit、fixed:根据原图尺寸比例计算另一个参数构造缩放矩形框
- b.fill、pad:根据指定的参数构造一个正方形缩放矩形框
- 3.如果不含w和h参数:
- a.如果同时包含l和s参数:
- i.缩放矩形框的长边设置为l,短边设置为s
- b.l和s仅指定一个:
- i.lfit、mfit、fixed:根据原图尺寸比例计算另一个参数构造缩放矩形框
- ii.fill、pad:根据指定的参数构造一个正方形缩放矩形框
- c.如果不含l和s参数:使用p参数进行等比例缩放。
参数计算举例
原图尺寸:400×200
- 1.用户指定缩放参数w为100,h为100,根据参数优先级,使用w和h构造缩放矩形,尺寸100×100:
- a.lfit模式:原图等比缩 小,缩放矩形框刚好能完全包含缩放图片时,即为该模式的缩放结果(100×50)。
- b.mfit模式:原图等比缩小,缩放图片刚好能完全覆盖缩放矩形框时,即为该模式的缩放结果(200×100)。
- c.fixed模式:按指定宽、高强制缩放(100×100)。
- d.fill模式:先进行mfit缩放,然后将缩放图片和缩放矩形框中心对齐,将缩放图片超出缩放矩形的部分裁剪掉(100×100)。
- e.pad模式:先进行lfit缩放,然后将缩放图片和缩放矩形框中心对齐,对于空白的区域使用指定颜色填充(100×100)。
- 2.用户指定缩放参数w为200,根据参数的优先级说明,原图宽、高比为2:1,计算h为100,此时缩放矩形框大小为200×100,之后同上进行缩放操作。
- 3.用户指定缩放参数l为200,s为100 ,此时缩放矩形框的长边为200,短边为100,由于原图宽为长边、高为短边,因此等效于200×100的缩放矩形框,之后同上进行缩放操作。
- 4.用户指定缩放参数l为200,原图宽为长边,且宽、高比为2:1,因此此时等效于200×100的缩放矩形框,之后同上进行缩放操作。
示例
- •指定缩放宽度为100,进行等比缩放
- •指定缩放高度为100,进行等比缩放
- •指定缩放长边为100,进行等比缩放
- •指定缩放短边为100,进行等比缩放
- •指定缩放宽度为200,高度为200,模式为lfit
- •指定缩放高度为200,高度为200,模式为mfit
- •指定缩放高度为200,高度为200,模式为fixed
- •指定缩放高度为200,高度为200,模式为fill
- •指定缩放高度为200,高度为100,模式为pad,填充颜色为红色FF0000
- •等比缩小为30%
水印功能
图片水印功能(watermark)可以为 TOS 存储桶内的图片添加文字水印、图片水印以及图文水印。
基础参数
基础参数为文字水印和图片水印均可使用的参数,具体参数如下所示。
参数 | 参数说明 | 取值说明 | 是否必须 |
t | 文字或图片水印的透明度。 | [0,100] 默认值:100, 表示透明度100%(不透明)。 | 否 |
g | 水印在图片中的放置位置。 |
| 否 |
x | 水印的水平边距, 即距离图片边缘的水平距离。这个参数只有当水印位置是左上、左中、左下、右上、右中、右下才有意义。 | [0,4096] 默认值:10 单位:像素(px) | 否 |
y | 水印的垂直边距,即距离图片边缘的垂直距离, 这个参数只有当水印位置是左上、中上、右上、左下、中下、右下才有意义。 | [0,4096] 默认值:10 单位:px | 否 |
voffset | 水印的中线垂直偏移。当水印位置在左中、中部、右中时,可以指定水印位置根据中线往上或者往下偏移。 | [-1000,1000] 默认值:0 单位:px | 否 |
图片水印
图片水印参数可以指定水印图片以及水印图片的预处理参数,具体参数如下所示。
示例:使用 watermark.jpg 作为水印图片,经过 url 安全的 base64 编码处理之后变为,图片水印的最终参数为image/watermark,image_d2F0ZXJtYXJrLmpwZw
。
参数 | 参数说明 | 取值说明 | 是否必须 |
image | 水印图片的对象名称,需要进行url安全的base64编码,且必须与目标图片位于同一个存储桶内。 | base64编码的字符串。 | 添加水印图片时必须 |
P | 对水印图片进行百分比缩放。 | resize功能特殊参数,只能在水印图片预处理过程中使用。 | 否 |
其他预处理操作 | 对水印图片进行预处理。 | 图片缩放、自定义裁剪、索引切割、以及图片旋转操作中的所有功能对水印图片进行预处理。 | 否 |
注意事项:水印图片预处理参数是 image 的参数值,也需要进行 base64 编码,例如使用 watermark.jpg 作为水印图片,并对其进行 30%的缩放预处理,原始参数为image_watermark.jpg?x-tos-process=image/resize,P_30
,url 安全的 base64 编码之后为image_d2F0ZXJtYXJrLmpwZz94LXRvcy1wcm9jZXNzPWltYWdlL3Jlc2l6ZSxQXzMw
。
文字水印
文字水印参数可以指定文字内容、文字大小、文字类型以及文字颜色等,具体参数如下所示。
示例:使用"Hello world"作为水印文字,字体选择方正书宋,顺时针旋转 45 度,原始参数为text_Hello world,type_fangzhengshusong,rotate_45
,文字内容以及字体经过 url 安全的 base64 编码之后为参数为text_SGVsbG8gd29ybGQ,type_ZmFuZ3poZW5nc2h1c29uZw,rotate_45
。
参数 | 参数说明 | 取值说明 | 是否必须 |
text | 文字水印内容,需要进行url安全的base64编码。 | 编码之前中文字符串的最大字节长度为 | 添加文字水印时必须 |
type | 文字水印的字体,需要进行url安全的base64编码。 | 可选字体为文泉驿正黑(默认)、文泉微米黑、方正书宋、方正楷体、方正黑体、方正仿宋、DroidSansFallback,字体的具体编码详见文字类型编码对应表。 | 否 |
color | 文字水印的颜色。 | 十六进制颜色码,取值为000000到FFFFFF,默认值为000000(黑色)。 | 否 |
size | 文字水印的文字大小。 | (0,1000] 默认值:40 单位:px | 否 |
shadow | 文字水印的阴影透明度。 | [0,100] 默认值:0,表示没有阴影。 | 否 |
rotate | 文字水印按顺时针方向旋转的角度。 | [0,360] 默认值:0,表示不旋转。 | 否 |
fill | 是否将水印文字平铺满原图。 |
| 否 |
type参数中可选的文字类型及编码如下表所示。
原始参数 | url安全的base64编码 | 字体名称 | 备注 |
wqy-zenhei | d3F5LXplbmhlaQ | 文泉驿正黑 | 已省略填充符= |
wqy-microhei | d3F5LW1pY3JvaGVp | 文泉微米黑 | |
fangzhengshusong | ZmFuZ3poZW5nc2h1c29uZw | 方正书宋 | 可省略填充符= |
fangzhengkaiti | ZmFuZ3poZW5na2FpdGk | 方正楷体 | 可省略填充符= |
fangzhengheiti | ZmFuZ3poZW5naGVpdGk | 方正黑体 | 可省略填充符= |
fangzhengfangsong | ZmFuZ3poZW5nZmFuZ3Nvbmc | 方正仿宋 | 可省略填充符= |
droidsansfallback | ZHJvaWRzYW5zZmFsbGJhY2s | DroidSansFallback | 可省略填充符= |
图文混合水印
在一个水印功能中同时指定图片和文字水印,通过图文混合水印参数可以调整图片和文字的排列关系,具体参数如下所示。
参数 | 参数说明 | 取值说明 | 是否必须 |
order | 文字水印和图片水印的前后顺序。 |
| 否 |
align | 文字水印和图片水印的对齐方式。 |
| 否 |
interval | 文字水印和图片水印间的间距。 | [0,1000] 默认值:0 单位:px | 否 |
示例
文字水印示例
- •添加文字水印,文字内容为Hello,文字大小设置为72,颜色设置为红色,字体设置为方正书宋。
- •添加文字水印,水印位置居中,文字顺时针旋转45度,其他参数同上。
- •添加文字水印,平铺原图,其他参数同上。
- 1.图片水印示例
- •原图等比缩放 60%,直接添加图片水印,水印使用默认参数,misc/watermark2.png编码为bWlzYy93YXRlcm1hcmsyLnBuZw==。
- •添加图片水印,水印位置居中,顺时针旋转45度,其他参数同上。
图文混合水印
说明:该处图文混合水印是指在一个 watermark 功能中同时指定文字和图片水印,用户可以通过图文混合水印参数调整文字和图片的排布方式。
- •图文混合水印,默认参数。
- •图文混合水印,文字在左,图片在右,中线对齐,文字、图片间隔100。
添加多个图片和文字水印
- •添加图片水印misc/watermark2.png,以及两个文字水印“Hello World”和“你好”。
- •原图等比缩放50%
- •“Hello World”文字大小60,字体为方正书宋,位置右上角,颜色黑色000000
- •“你好”文字大小50,字体为方正楷体,位置居中,颜色红色FF0000
自定义裁剪
自定义裁剪功能(crop),指定原图上的任意一点作为起始坐标,根据指定的宽高裁剪出矩形区域,具体参数如下所示。
参数说明
参数 | 参数说明 | 取值说明 | 是否必须 |
g | 裁剪的起始坐标原点。 |
| 否 |
w | 裁剪宽度。 | [0,图片宽度] 默认为最大值。 | 否 |
h | 裁剪高度。 | [0,图片高度] 默认为最大值。 | 否 |
x | 裁剪起始点横坐标偏移(相对于指定的坐标原点)。 | 横坐标向右偏移为正,向左偏移为负 | 否 |
y | 裁剪起始点纵坐标偏移(相对于指定的坐标原点)。 | 纵坐标向下偏移为正,向上偏移Wie负 | 否 |
各裁剪起始坐标原点的计算方法如下,其中 srcW 代表原图宽度,srcH 代表原图高度。
裁剪原点 | 位置计算方法 |
nw | 0, 0 |
north | srcW/2 - w/2, 0 |
ne | srcW - w, 0 |
west | 0, srcH/2 - h/2 |
center | srcW/2 - w/2, srcH/2 - h/2 |
east | srcW - w, srcH/2 - h/2 |
sw | 0, srcH - h |
sourth | srcW/2 - w/2, srcH - h |
se | srcW - w, srcH - h |
注意事项
- •如果最终计算的坐标原点超出了原图范围,将会返回BadRequest错误,错误信息为Advance cut's position is out of image。
- •如果从坐标原点开始指定的宽度和高度超过了原图范围,将会直接裁剪到原图边界为止。
- •如果输入多帧图片,
示例
- •裁剪坐标原点使用默认值,宽、高均设置为400,不设置x、y偏移量。
- •裁剪坐标原点使用默认值,宽、高均设置为400,设置x偏移量50,设置y偏移量50。
内切圆
内切圆功能(circle)以图片的中心为圆心,根据指定的半径进行裁剪,具体参数如下所示。
参数说明
参数 | 参数说明 | 取值说明 | 是否必须 |
r | 内切圆的半径 | [1,4096] | 是 |
注意事项
- •如果图片的输出格式不支持透明通道,比如jpg,那么非圆形区域以白色填充;如果图片的输入格式支持透明通道,比如png、webp、bmp等矢量图格式,则非圆形区域以透明填充,推荐保存成png格式。
- •当半径的取值超过原图最短边的一半时,以原图最小边的一半作为内切圆半径。
示例
- •裁剪半径设置200,保存格式jpg,外围区域以白色填充。
- •裁剪半径设置200,保存格式png,外围区域以透明填充。
索引切割
所有切割功能(indexcrop)以左上角顶点为起始点,宽为 x 轴,高为 y 轴。将原图按照指定的大小进行分割,根据索引返回切割后的图片,具体参数如下所示。
参数说明
参数 | 参数说明 | 取值说明 | 是否必须 |
x | x方向剪切的每块图片长度。 | [1,图片宽度]。x和y参数只能任选其一。 | 是 |
y | y方向剪切的每块图片长度。 | [1,图片高度]。x和y参数只能任选其一。 | 是 |
i | 取第i块 | 若剪切后一共有n块,则i的取值范围为[0,n-1],默认为0。 | 否 |
注意事项
- •若剪切后一共有n块,则i的取值范围为[0,n-1]。0表示第一块,超过最大的块数则返回原图。
- •当x和y同时指定且值合法时,以y参数的值为准。
示例
- •x方向切割长度200,取第一块。
- •y方向切割长度200,取第一块。
- •同时指定x和y为200,取第一块。
圆角矩形
圆角矩形功能(rounded-corners)指定圆角大小将原图裁剪为圆角矩形,具体参数如下。
参数说明
参数 | 参数说明 | 取值说明 | 是否必须 |
r | 圆角半径 | [1,4096] | 是 |
注意事项
- •如果图片的输出格式不支持透明通道,比如jpg,那么非圆形区域以白色填充;如果图片的输入格式支持透明通道,比如png、webp、bmp等矢量图格式,则非圆形区域以透明填充,推荐保存成png格式。
- •当圆角半径的取值超过原图最短边的一半时,则按照图片最大内切圆的半径设置圆角。
示例
- •圆角半径设置为100,保存格式jpg,外围区域以白色填充。
- •圆角半径设置为100,保存格式png,外围区域以透明填充。
质量变换
质量变换功能(quality)可以对原图进行压缩,调整原图的质量,具体参数如下所示。
参数说明
参数 | 参数说明 | 取值说明 | 是否必须 |
q | 相对质量,将图片按照原图的q%进行压缩。 | [1,100] | 是 |
Q | 绝对质量,即直接将图片压缩为Q%,与原图不存在相对关系,不依赖于原图。 | [1,100] | 是 |
注意事项
- •质量变换仅支持jpg和webp格式,其他图片格式不支持。
- •q参数只对jpg格式的原图有效。
- •如果同时使用了q和Q参数,则以Q为输出结果。
示例
- •相对质量60%,输出格式jpg。
- •绝对质量60%,输出格式jpg。
格式转换
格式转换功能(format)可以将原图转换为支持的图片格式,具体参数如下所示。
参数说明
参数 | 参数说明 | 取值说明 | 是否必须 |
jpg | 保存为jpg格式。 | 如果原图是PNG、WebP、BMP等存在透明通道的格式,默认会把透明填充成白色。 | 是 |
png | 保存为png格式。 | | 是 |
webp | 保存为webp格式。 | | 是 |
bmp | 保存为bmp格式。 | | 是 |
gif | 保存为gif格式。 | 如果原图是gif,则继续保持为gif;如果原图不是gif,则按原图格式进行保存。 | 是 |
tiff | 保存为tiff格式。 | | 是 |
注意事项
- •图片处理包含缩放操作时,建议将格式转换参数放到处理参数的最后。
获取信息
获取信息功能(info)可以获取到图片的基本信息:长、宽、以及文件的大小和格式。如果图片包含 Exif 信息,也将按照 json 格式返回。
参数说明
参数 | 参数说明 | 取值说明 | 是否必须 |
无 | - | - | - |
示例
- •查询图片的信息。
{ "FileSize": { "value": "438212" }, "Format": { "value": "png" }, "ImageHeight": { "value": "683" }, "ImageWidth": { "value": "1023" } }
获取图片主色调
获取图片主色调功能(average-hue)可以获取图片的平均色值,平均色值将以 json 格式返回一个十六进制值。
参数说明
参数 | 参数说明 | 取值说明 | 是否必须 |
无 | - | - | - |
示例
- •获取图片主色调
{ "RGB": "0x5A79A1" }
获取到的平均色值(#5A79A1)对应的颜色为:
自适应方向
自适应方向功能(auto-orient)可以设置原图是否按自适应方向旋转(在一些相机或手机拍摄的图片中会含有 Exif 信息,其中可能包含例如 Orientation 的方向参数),具体参数如下所示。
参数说明
参数 | 参数说明 | 取值说明 | 是否必须 |
value | 图片是否进行自适应旋转 |
| 是 |
注意事项
- •如果原图没有旋转参数(Orientation),则使用auto-orient参数操作无效且对图片无任何影响。
示例
- •图片宽度设置为200,不设 置自适应方向。
模糊
模糊功能(blur)可以为原图增加模糊效果,具体参数如下所示。
参数说明
参数 | 参数说明 | 取值说明 | 是否必须 |
r | 模糊半径。 | [1,50] 该值越大,图片越模糊。 | 是 |
s | 正态分布标准差。 | [1,50] 该值越大,图片越模糊。 | 是 |
注意事项
动态图将会变成静态图。
示例
- •设置图片模糊效果,r为3,s为2。
旋转
图片旋转功能(rotate)会将图片按顺时针方向进行旋转,具体参数如下所示。
参数说明
参数 | 参数说明 | 取值说明 | 是否必须 |
value | 图片顺时针旋转的角度 | 图片将会按顺时针方向进行旋转。 | 是 |
注意事项
- •若图片旋转的角度不是90°、180°、270°、360°时,会导致处理后的图片尺寸变大。
- •旋转功能对图片的尺寸有限制,图片的宽或者高不能超过4096 px。
示例
- •图片宽度设置为200,顺时针旋转角度设置为90。
- •图片宽度设置为200,顺时针旋转角度设置为245。
渐进显示
渐进显示功能(interlace)可以将原图修改为渐进显示,具体参数如下所示。
参数说明
参数 | 参数说明 | 取值说明 | 是否必须 |
value | 是否设置图片为渐进显示。 | 0、1
| 是 |
注意事项
- •渐进显示功能仅适用于jpg格式图片,对于其他格式需要先使用format功能先转换为jpg格式。
- •对于非jpg格式的图片,将不产生影响。
示例
- •为图片设置渐进显示效果。
亮度
亮度功能(bright)可以调节原图的亮度,具体参数如下所示。
参数说明
参数 | 参数说明 | 取值说明 | 是否必须 |
value | 图片的亮度 | [-100, 100]
| 是 |
注意事项
动态图变静态图
示例
- •图片宽度设置为200,亮度降低50。
- •图片宽度设置为200,亮度提高50。
锐化
锐化功能(sharpen)可以调节原图的锐化效果。
参数说明
参数 | 参数说明 | 取值说明 | 是否必须 |
value | 图片锐化程度 | [50,399] 取值越大,图片越清晰,但过大的值可能会导致图片失真。为达到较优效果,推荐取值为100。 | 是 |
示例
- •锐化参数设置为100。
对比度
对比度功能(contrast)可以调节原图的对比度,具体参数如下所示。
参数说明
参数 | 参数说明 | 取值说明 | 是否必须 |
value | 图片对比度 | [-100,100]
| 是 |
示例
- •图片宽度设置为200,对比度降低50。
- •图片宽度设置为200,对比度提高50。
异常情况说明
- 1.resize图片过大
- a.oss正常处理
- b.obs报错503
- 2.resize GIF动图
- a.oss忽略放大操作,对于缩小操作某些场景也忽略(比如pad模式)
- b.obs对于动图几乎完全不处理
- 3.rounded-corners非常耗费内存
- 4.blur图片过大
- a.oss正常
- b.obs报错503