对象存储图像处理

收藏
我的收藏

简介

针对 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
图片缩放模式
    lfit(默认值):根据w和h构造一个缩放矩形框,对原图进行等比缩放,缩放过程中全部落入缩放矩形框中的最大图片作为lfit缩放结果。
    mfit:根据w和h构造一个缩放矩形框,对原图进行等比缩放,缩放过程中完全覆盖缩放矩形框的最小图片作为mfit缩放结果。
    fill:根据w和h构造一个缩放矩形框,对原图进行等比缩放,首先确定完全覆盖缩放矩形框的最小图片(即mfit),然后按照缩放矩形框大小进行居中裁剪。
    pad:根据w和h构造一个缩放矩形框,对原图进行等比缩放,首先确定完全落入缩放矩形框的最大图片(即lfit),然后在缩放矩形框内居中放置该图片,并对剩余空白区域进行颜色填充(color参数)。
    fixed:强制按照固定的宽、高进行缩放。
w
目标缩放图宽度
[1,16384]
h
目标略缩图高度
[1,16384]
l
目标缩放图长边
[1,16384]
s
目标缩放图短边
[1,16384]
limit
指定目标缩放图大于原图时是否进行缩放
    1(默认值):不按指定参数进行缩放,直接返回原图。
    0:按指定参数进行缩放。
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的缩放矩形框,之后同上进行缩放操作。

示例

原图:https://tos-tools.tos-cn-beijing.volces.com/misc/sample.png(后文静态图片均使用该图片进行测试)
    指定缩放宽度为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
水印在图片中的放置位置。
    nw:左上
    north:中上
    ne:右上
    west:左中
    center:中部
    east:右中
    sw:左下
    south:中下
    se(默认值):右下
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编码。
编码之前中文字符串的最大字节长度为64个字符
添加文字水印时必须
type
文字水印的字体,需要进行url安全的base64编码。
可选字体为文泉驿正黑(默认)、文泉微米黑、方正书宋、方正楷体、方正黑体、方正仿宋、DroidSansFallback,字体的具体编码详见文字类型编码对应表。
color
文字水印的颜色。
十六进制颜色码,取值为000000到FFFFFF,默认值为000000(黑色)。
size
文字水印的文字大小。
(0,1000]
默认值:40
单位:px
shadow
文字水印的阴影透明度。
[0,100]
默认值:0,表示没有阴影。
rotate
文字水印按顺时针方向旋转的角度。
[0,360]
默认值:0,表示不旋转。
fill
是否将水印文字平铺满原图。
    1:表示将文字水印铺满原图。
    0(默认值):表示不将文字水印铺满全图。
type参数中可选的文字类型及编码如下表所示。
原始参数
url安全的base64编码
字体名称
备注
wqy-zenhei
d3F5LXplbmhlaQ
文泉驿正黑
已省略填充符=
wqy-microhei
d3F5LW1pY3JvaGVp
文泉微米黑
fangzhengshusong
ZmFuZ3poZW5nc2h1c29uZw
方正书宋
可省略填充符=
fangzhengkaiti
ZmFuZ3poZW5na2FpdGk
方正楷体
可省略填充符=
fangzhengheiti
ZmFuZ3poZW5naGVpdGk
方正黑体
可省略填充符=
fangzhengfangsong
ZmFuZ3poZW5nZmFuZ3Nvbmc
方正仿宋
可省略填充符=
droidsansfallback
ZHJvaWRzYW5zZmFsbGJhY2s
DroidSansFallback
可省略填充符=

图文混合水印

在一个水印功能中同时指定图片和文字水印,通过图文混合水印参数可以调整图片和文字的排列关系,具体参数如下所示。
参数
参数说明
取值说明
是否必须
order
文字水印和图片水印的前后顺序。
    0(默认值):表示图片水印在前。
    1:表示文字水印在前。
align
文字水印和图片水印的对齐方式。
    0:表示文字水印和图片水印上对齐。
    1:表示文字水印和图片水印中对齐。
    2(默认值):表示文字水印和图片水印下对齐。
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
裁剪的起始坐标原点。
    nw(默认值):左上
    north:中上
    ne:右上
    west:左中
    center:中部
    east:右中
    sw:左下
    south:中下
    se:右下
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
图片是否进行自适应旋转
    0:保持原图方向,不进行自适应旋转。
    1:将图片进行自适应旋转。

注意事项

    如果原图没有旋转参数(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
    1:表示将原图设置成渐进显示。
    0:表示将原图设置成标准显示。

注意事项

    渐进显示功能仅适用于jpg格式图片,对于其他格式需要先使用format功能先转换为jpg格式。
    对于非jpg格式的图片,将不产生影响。

示例

    为图片设置渐进显示效果。

亮度

亮度功能(bright)可以调节原图的亮度,具体参数如下所示。

参数说明

参数
参数说明
取值说明
是否必须
value
图片的亮度
[-100, 100]
    取值<0:降低图片亮度。
    取值=0:不调整图片亮度。
    取值>0:提高图片亮度。

注意事项

动态图变静态图

示例

    图片宽度设置为200,亮度降低50。
    图片宽度设置为200,亮度提高50。

锐化

锐化功能(sharpen)可以调节原图的锐化效果。

参数说明

参数
参数说明
取值说明
是否必须
value
图片锐化程度
[50,399]
取值越大,图片越清晰,但过大的值可能会导致图片失真。为达到较优效果,推荐取值为100。

示例

    锐化参数设置为100。

对比度

对比度功能(contrast)可以调节原图的对比度,具体参数如下所示。

参数说明

参数
参数说明
取值说明
是否必须
value
图片对比度
[-100,100]
    取值<0:降低图片对比度。
    取值=0:维持原图对比度。
    取值>0:提高图片对比度。

示例

    图片宽度设置为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