图片处理V1.0
基本概念
图片服务域名
图片服务域名,是指用来访问图片服务的域名。图片服务和普通BOS访问使用的是同一个域名,系统会为Bucket提供一个外网直接发布的官方域名即<bucketname>.region.bcebos.com
,用户也可以添加自定义域名。如果Bucket开通了CDN加速发布,则图片服务同步开通CDN加速。如果要开通Bucket的CDN加速发布,可参考CDN加速发布。
说明:Console升级后不影响已有域名的图片处理。前期官方提供的bceimg.com域名主要用于客户试用图片服务,升级后将没有存在意义。对于已开通的bceimg.com域名,可继续使用半年,后续会收回。
访问URL
图片处理服务使用通过URL来访问处理的图片。
URL的构成请参考URL构成。
处理命令
处理命令是指URL中用来转换处理图片的一段命令,形式为“缩写命令_参数值”。通过指定的处理命令参数值,BOS生成并返回另一张转换处理后的图片。如“w_250”,表示将图片的宽度处理为250 px。
执行图片某一类处理方式的命令可称为一组命令,如:执行图片缩放功能为一组命令,执行图片裁剪功能为另一组命令。
分隔符
分隔符是指URL中用来区分一些关键字段的分隔符号。
分隔符名称 | 分隔符 | 两侧顺序 | 说明 |
---|---|---|---|
处理分隔符 | @ | 固定顺序 | Object与处理命令之间的分隔符 |
参数分隔符 | _ | 固定顺序 | 参数缩略命令与参数值之间的分隔符 |
命令分隔符 | , | 无关 | 多项处理参数项之间的分隔符 |
管道分隔符 | | | 有关 | 两组处理命令之间分隔符,管道的参见下述“管道” |
管道
如果一个图片,需要多重处理,如先裁剪、后缩略等,则多组操作命令之间,需要以管道“|”连接,执行顺序按管道指定顺序从左至右执行。
例如:http://${userdomain}/${objectkey}@${cropcommands}|${scalecommands}
为一个管道,执行顺序为从左到右,左侧命令处理结果将会作为右侧命令的输入。
样式
在对图片进行多重处理时,图片访问的URL会变得复杂冗长,非常不利于管理和阅读。为了让图片URL变得更简洁优雅,或是您想达到隐藏处理参数、保护原图的目的时,您可以使用图片样式功能。
图片样式是指您可以将一些常用的图片处理操作保存为一个别名,即一个样式。这样,一组复杂的操作,利用样式,可以通过一个简洁的URL访问即可达到相同效果。
URL构成
直接显示原图
直接显示原图与普通的域名绑定访问方式一样,URL形式为:http://${userdomain}/${objectkey}
userdomain
为用户绑定的域名。objectkey
为存储在BOS上的原图片名称。
样例:http://www.myhost.com/pic.jpg
通过处理命令访问
URL形式为:http://${userdomain}/${objectkey}@${commands}
userdomain
为用户绑定的域名。objectkey
为存储在BOS上的原图片名称。commands
为处理命令。
样例:http://bucket-A.bj.bcebos.com/sample.jpg@w_200,q_80
通过样式访问
URL形式为:http://${userdomain}/${objectkey}@!${stylename}
userdomain
为用户绑定的域名。objectkey
为存储在BOS上的原图片名称。stylename
为样式。
样例:http://bucket-A.bj.bcebos.com/sample.jpg@!stylename
规则和限制
支持图片规格
- 支持的原图格式:jpg、png、bmp、webp、gif、tiff。
- 支持的目标图格式:jpg、png、bmp、webp。
- 支持图片大小为100MB,且图片长和宽不大于4096 px。
域名绑定规则
- 一个Bucket绑定的域名数(包括图片域名)不能超过20个,其中图片域名不超过1个。
- 对于同一个域名,只支持一种绑定方式,在普通域名绑定或图片域名绑定中选择一种,不支持两种方式同时绑定。
请求规则
- 对于同一组处理命令的参数处理采用无序原则,如
@w_250,h_380,q_90
等同于@h_380,w_250,q_90
。 - 如果获取的Object名称本身带有@符号时,其后字符全部按照处理命令对待,用户需要提前替换Object 名称中的@符号。
- 最大支持4个管道。
访问限制
Authorization的签名计算与普通Object处理方式类似,但必须将带参数的图片名称作为一个完整的URL Path用于签名。如带水印的图片签名计算的URL应该为http://test.gz.bcebos.com/IMG_5974.JPG@!shuiyin1?authorization=...
,其中参与签名的URL Path为IMG_5974.JPG@!shuiyin1
。
图片处理命令
图片缩放、旋转、渐进显示
命令参数
参数名称 | 缩写命令 | 类型 | 取值范围 | 命令描述 | 缺省值 | 是否必选 |
---|---|---|---|---|---|---|
scale | s | unsigned int | 0,1,2 | 指定缩放方式。 s_0表示无裁剪,等比例缩放; s_1表示拉伸缩放; s_2表示等比例居中裁剪缩放。 |
0 | 否 |
width | w | unsigned int | 1~4096 | 指定目标缩略图的最大宽度 单位为px。 |
- | s_1, s_2时, 必选 |
height | h | unsigned int | 1~4096 | 指定目标缩略图的最大高度 单位为px。 |
- | s_1, s_2时, 必选 |
quality | q | unsigned int | 1~100 | 指定目标图片的绝对质量, 只对jpg/jpeg、png、 webp 格式有效。 当指定q命令的值大于原图 quality的值时,则默认使用原 图quality的值。 |
原图 quality值。 |
否 |
format | f | string | jpg、 png、 webp、 bmp |
指定目标图片格式。 响应时对应的Content-Type 分别为image/jpeg、image /png、image/webp、image /bmp。 |
jpg | 否 |
angle | a | int | -360~360 | 指定图片旋转方式。 正数表示顺时针旋转,如 a_60 ;负数表示逆时针旋转,如 a_-30 。 |
0 | 否 |
orientation | o | int | 0,1,2 | 根据exif信息进行自动旋转。o_0 :按原图默认方向,不自动旋转;o_1 :先旋转,然后再缩略;o_2 :先缩略,然后再旋转。 |
0 | 否 |
display | d | string | baseline progressive |
指定图片显示方式。baseline :标准式,指图片按照从上到下的扫描方式显示; progressive :渐进式 ,指图片由模糊到清晰渐进显示。 progressive 只对jpg、png格式图片有效,若指定其他格式, 则默认显示方式仍为 baseline 。 |
baseline |
否 |
limit | l | unsigned int | 0,1 | 指定是否限制图片缩放的尺寸 大小。l_0表示不限制图片缩放 的尺寸;l_1表示限制图片缩放 尺寸(长和宽)不可超过原图 大小。 |
0 | 否 |
注意事项:
当s_0时,即无裁剪等比缩放时:
w和h可以只指定其中一个,图片按指定的参数比例进行缩放。 例如,原图尺寸为100 × 200,指定参数为w_50后,图片处理的尺寸为50 × 100;若指定h_50后,图片处理的尺寸为25 × 50。
- w和h同时指定时,系统会取“目标宽度/原图宽度”与“目标高度/原图高度”中值小的参数为标准进行等比例缩放。
例如:原图尺寸为400 × 500 ,指定参数为w_100,h_200时,由于“100/400”< “200/500”,则系统按照w_100的比例进行缩放,目标尺寸为100 × 125。- 当s_1时,必须同时指定w和h的值,若不同时指定,访问会报错。
当s_2时,必须同时指定w和h的值,若不同时指定,访问会报错。指定w和h后,图片会按照“目标宽度/原图宽度”与“目标高度/原图高度”中值小的参数为标准进行等比例缩放,并对比值较大的另一边进行居中裁剪。
例如:原图尺寸为500 × 1000 ,指定参数为s_2,w_250,h_600时,由于“250/500” < “600/1000”,会以目标宽度250为基准进行等比缩放,同时将高度按照居中裁剪为500。
示例
-
将图片缩略成高度为200,宽度按比例处理。
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@h_200
-
将图片缩略成宽度为150,高度为200,目标图片绝对质量为60,目标图片格式为png。
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@s_1,w_150,h_200,q_60,f_png
-
将图片进行等比例居中裁剪缩放,缩放宽度为80,高度为100。
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@s_2,w_80,h_100
-
将图片顺时针旋转30度。
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@a_30
-
将图片缩略成宽度为150,高度为100,逆时针旋转90度,并渐进显示。
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@s_1,w_150,h_100,a_-90,d_progressive
图片裁剪
命令参数
参数名称 | 缩写命令 | 类型 | 取值范围 | 命令描述 | 缺省值 | 是否必选 |
---|---|---|---|---|---|---|
crop | c | unsigned int | 0,1 | 指定图片是否执行裁剪功能。 c_1表示对图片进行裁剪; c_0表示不对图片进行裁剪, 其他裁剪参数无效。 |
- | 否 |
offsetX | x | unsigned int | 0~4096 | 指定图片裁剪左上角起点x坐标。 | 0 | 否 |
offsetY | y | unsigned int | 0~4096 | 指定图片裁剪左上角起点y坐标。 | 0 | 否 |
width | w | unsigned int | 1~4096 | 指定图片裁剪的宽度。 如果指定的宽度超过了图片的 宽度,则以图片宽度为准裁剪。 单位为px。 |
原始图片宽度 | 否 |
height | h | unsigned int | 1~4096 | 指定图片裁剪的高度。 如果指定的高度超过了图片的 高度,则以图片高度为准裁剪。 单位为px。 |
原始图片高度 | 否 |
示例
-
以图片左上角横坐标为100,纵坐标为150为起点进行图片裁剪,裁剪宽度和高度默认为原始图片宽度和高度。
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@c_1,x_100,y_150
-
以图片左上角横、纵坐标均为0为起点进行图片裁剪,裁剪宽度指定为600,裁剪高度指定为600。
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@c_1,w_600,h_600
-
以图片左上角横坐标为100,纵坐标为150为起点进行图片裁剪,裁剪宽度指定为400,裁剪高度指定为200。
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@c_1,x_100,y_150,w_400,h_200
图片水印命令
图片水印是指在图片上方插入另一张图片或者文字作为水印,是一种数字信息的保护手段。
目前百度智能云支持图片水印和文字水印两种水印方式。
在了解图片水印命令前,您需要先了解图片锚点的含义。
图片锚点
将您的原始图片分成如下图所示9个区域,并按照图示位置进行编号,每个区域的锚点位置如图所示:
确定水印在原图上的最终位置,您需要确定如下两个因素:
- 锚点位置;
- 基于锚点位置,指定在水平和垂直方向上的距离。
图片水印
命令参数
参数名称 | 缩写命令 | 类型 | 取值范围 | 命令描述 | 缺省值 | 是否必选 |
---|---|---|---|---|---|---|
watermark | wm | unsigned | 0,1,2 | 指定水印方式。 wm_0表示关闭水印功能; wm_1表示图片水印; wm_2表示文字水印。 |
- | 是 |
key | k | string | - | 指定水印图片存储在BOS上的 Object名称,即ObjectKey。 如Object存储在文件夹下,则 需要包含文件夹路径。 该值要求为Base64编码后的值。 |
- | 是 |
gravity | g | unsigned int | 1~9 | 指定水印的锚点位置。 图片锚点的含义请参考图片水印命令。 |
9 | 否 |
gravityX | x | int | -4096~4096 | 指定水印基于锚点的水平方向距离。 | 10 | 否 |
gravityY | y | int | -4096~4096 | 指定水印基于锚点的垂直方向距离。 | 10 | 否 |
angle | a | int | -360~360 | 指定水印图片的旋转角度。 正数表示顺时针旋转,如 a_60 ;负数表示逆时针旋转,如 a_-30 。 |
0 | 否 |
opacity | o | unsigned int | 1~100 | 指定水印图片的透明度。 取值为100时,表示与原始 图片透明度一致。 |
100 | 否 |
说明
水印图片要与原始图片存储在BOS的同一个Bucket下。
示例
原图为image.jpg,水印图片为bce-documentation/BOS/bce.jpg(Base64编码后为“YmNlLWRvY3VtZW50YXRpb24vQk9TL2JjZS5qcGc=”)。
-
在右下角加上图片水印,指定垂直距离为10,透明度为60。
-
在左下角加上水印,水平和垂直距离取缺省值,透明度为50,并顺时针旋转90度。
文字水印
命令参数
参数名称 | 缩写命令 | 类型 | 取值范围 | 命令描述 | 缺省值 | 是否必选 |
---|---|---|---|---|---|---|
watermark | wm | unsigned | 0,1,2 | 指定水印方式。 wm_0表示关闭水印功能; wm_1表示图片水印; wm_2表示文字水印。 |
- | 是 |
text | t | string | - | 水印文字内容,需要进行 Base64编码,且编码后最 多不能超过80个字符。 |
- | 是 |
gravity | g | unsigned int |
1~9 | 指定水印的锚点位置。图片 锚点的含义请参考图片水印命令。 |
9 | 否 |
gravityX | x | int | -4096~4096 | 指定水印基于锚点的水平方 向距离。 |
10 | 否 |
gravityY | y | int | -4096~4096 | 指定水印基于锚点的垂直方 向距离。 |
10 | 否 |
angle | a | int | -360~360 | 指定水印图片的旋转角度。 正数表示顺时针旋转,如 a_60 ;负数表示逆时针旋转,如 a_-30 。 |
0 | 否 |
fontSize | sz | unsigned int |
1~1024 | 指定水印字体大小,单位 是 px。 |
30 | 否 |
fontColor | fc | string | - | 指定字体颜色,为一个8位 的16进制字符串,其中每2 位用来表示RGBA中的一项。 前6位分别表示RGB色,如 ffffff;最后2位表示Alpha 通道,可省略,省略时表示 不透明。 例如:000000ff表示黑色不 透明字体。 |
000000 | 否 |
fontFamily | ff | string | - | 指定字体的字体类型,取值 要求进行Base64编码。已支 持的字体类型请参见 下方列表。 |
宋体 | 否 |
fontStyle | fs | string | normal(常规) italic(斜体) bold(粗体) |
指定字体样式。 | normal | 否 |
已支持的字体类型:
参数取值 | 字体类型 |
---|---|
MicrosoftYaHei | 微软雅黑 |
FangSong | 仿宋 |
SimHei | 黑体 |
KaiTi | 楷体 |
SimSun | 宋体 |
FZBeiWeiKaiShuJianTi | 方正北魏楷书简体 |
FZBoYaSongJianTi | 方正博雅宋简体 |
FZCuHeiSongJianTi | 方正粗黑宋简体 |
FZLanTingZhongHeiJianTi | 方正兰亭中黑简体 |
FZZhengHei | 方正正黑 |
AvantGarde | AvantGarde |
Bookman | Bookman |
Courier | Courier |
Helvetica | Helvetica |
HelveticaNarrow | HelveticaNarrow |
NewCenturySchlbk | NewCenturySchlbk |
Palatino | Palatino |
Times | Times |
Symbol | Symbol |
说明:
- 只有当fontFamily支持fontStyle效果时,才会渲染文字效果。
- 若指定的字体样式不在当前已支持的fontFamily列表中,则显示效果为默认字体宋体。
示例
-
最简单的文字水印,文字内容为“hello world”。
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@wm_2,t_aGVsbG8gd29ybGQ=
-
文字内容为“hello world”,字体类型为微软雅黑,字体颜色和字体大小取默认值,字体样式为粗体,水印位置在右中,距离锚点水平距离20,垂直距离20,并顺时针旋转30度。
图文混合水印
图文混合水印是指将图片水印和文字水印同时打在原始图片上。
由于图片水印和文字水印为两组独立的命令,因此图文混合水印需要用管道实现。
示例
-
最简单的图文混合水印:图片为bce-documentation/BOS/bce.jpg,文字内容为“hello world”,其余参数均取默认值。
-
图文混合水印:水印图片为bce-documentation/BOS/bce.jpg,位于原图左下角,距离锚点水平距离为,15,垂直距离为20,透明度为50;文字内容为“hello world”,位于正上方,垂直距离为100,字体颜色为淡紫色。
获取图片信息
此命令用来获取图片信息,如果图片有exif信息则返回包含exif的完整信息,如果图片不包含exif信息,则返回图片的基本信息。
说明:exif信息记录了数码照片的属性信息和拍摄数据,并非每一张图片都包含exif信息。
返回的exif信息包含但不限于:
- dateTime
- dateTimeOriginal
- dateTimeDigitized
- format
- gpsLatitude
- gpsLatitudeRef
- gpsLongitude
- gpsLongitudeRef
- imageHeight
- imageWidth
- imageSize
- make
- model
- orientation
- resolutionX
- resolutionY
- resolutionUnit
示例
-
包含exif信息的图片示例:
https://doc.bce.baidu.com/bce-documentation/BOS/orient.jpg?exif
返回示例:
{ "dateTime": { "value": "2016-08-31T14:57:07Z" }, "dateTimeDigitized": { "value": "2016-08-31T14:57:07Z" }, "dateTimeOriginal": { "value": "2016-08-31T14:57:07Z" }, "format": { "value": "JPEG" }, "gpsLatitude": { "value": "40/1,2/1,3675/100" }, "gpsLatitudeRef": { "value": "N" }, "gpsLongitude": { "value": "116/1,16/1,257/100" }, "gpsLongitudeRef": { "value": "E" }, "imageHeight": { "value": "2448" }, "imageSize": { "value": "1225883" }, "imageWidth": { "value": "3264" }, "make": { "value": "Apple" }, "model": { "value": "iPhone 6" }, "resolutionUnit": { "value": "2" }, "resolutionX": { "value": "72/1" }, "resolutionY": { "value": "72/1" } }
-
不包含exif信息的图片示例:
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?exif
返回示例:
{ "format": { "value": "JPEG" }, "imageHeight": { "value": "296" }, "imageSize": { "value": "63506" }, "imageWidth": { "value": "279" } }
管道
管道用来连接实现多条独立命令的执行。
访问方式
管道的处理命令格式为http://${userdomain}/${objectkey}@${commands 1}|${commands 2}
,执行顺序按管道指定顺序从左至右执行。
示例
-
对图片先缩放、旋转,再裁剪。先按宽200的比例等比缩放并顺时针旋转90度,再以左上角横坐标为50,纵坐标为100为起点进行裁剪,裁剪宽度和高度默认为图片宽度和高度。
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@w_200,a_30|c_1,x_50,y_100
-
对图片先裁剪,再缩放。先以左上角横坐标为10,纵坐标为20进行裁剪,裁剪宽度指定为600,高度为300,再按宽200,高200进行拉伸缩放,并指定目标图片的绝对质量为60,目标图片格式为png。
-
图文混合水印:水印图片为bce-documentation/BOS/bce.jpg,位于原图左下角,距离锚点水平距离为,15,垂直距离为20,透明度为50;文字内容为“hello world”,位于正上方,垂直距离为100,字体颜色为淡紫色。
图片样式
图片样式是指您可以将一些常用的图片处理操作保存为一个别名,即一个样式。这样,一组复杂的操作,利用样式,可以通过一个简洁的URL访问即可达到相同效果。
访问方式
图片样式的访问方式为:http://${userdomain}/${objectkey}@!${stylename}
,其中stylename
为您定义的样式名称。
例如:您定义了一个名为“small”的样式,您的域名为51mingxi.com
,您的图片名称为image.jpg
,则您通过样式访问该图片的URL为http://51mingxi.com/image.jpg@!small
。
添加样式
您可以通过控制台进行图片样式的定义,同时还可以在定义的同时实时进行效果预览。
- 登录BOS控制台,进入您已开通图片服务的Bucket。点击左侧导航“图片服务”后,点击右侧页面中的“样式管理”。
-
点击“添加样式”,进入添加样式表单页面。您可根据需要,设定该样式的图片处理参数,同时您可在右侧的预览区域实时进行效果预览。
图片样式的设置方式支持“基础设置”和“高级设置”两种。
- 基础设置,您需要在页面上对下方的每一项处理参数进行手动设定。
- 高级设置,您可直接在框中直接输入图片处理命令参数。
创建好样式后,点击“保存”。
缩放说明
-
限定宽度,高度等比例。
您需要输入宽度,缩略时以宽度为基准,将高度等比例缩小。若输入宽度大于原图宽度,则返回原图。
例如:原图宽高尺寸为400 × 320,限定宽度200,高度等比例,生成缩略图尺寸为200×160;限定宽度500,高度等比例,生成缩略图尺寸为400×320。
-
限定高度,宽度等比例。
您需要输入高度,缩略时以高度为基准,将宽度等比例缩小。若输入高度大于原图高度,则返回原图。
例如:原图宽高尺寸为400 × 320,限定高度160,宽度等比例,生成缩略图尺寸为200×160;限定高度500,宽度等比例,生成缩略图尺寸为400×320。
-
限定宽度和高度。
您需要输入宽度和高度,图片会保持原图比例进行缩略,直至宽、高都满足设定值,不裁剪。
例如:原图宽高尺寸为400 × 320,限定宽度为100,高度为100,生成缩略图尺寸为100 × 80;限定宽度为500,高度为500,生成缩略图尺寸为400×320。
-
固定宽度和高度。
您需要输入宽度和高度,图片会保持原图比例先进行缩略,超出设定宽、高部分进行居中裁剪。
例如:原图宽高尺寸为400 × 320 ,固定宽度100和高度100(缩小较大图片,并裁剪图片),生成缩略图尺寸为100×100;固定宽度500和高度500(放大较小图片,并裁剪图片),生成缩略图尺寸为500×500。
-
保存样式后,在列表中可以看到您已经添加的样式信息。您可以点击“查看命令”,查看样式对应的参数命令。
删除样式
在样式管理列表中,点击“操作”列的“删除”,可删除样式。
示例
例如定义了如下样式:
样式名 | 样式参数 |
---|---|
small | s_0,h_600,l_1,a_10,f_png,q_80 | wm_2,t_aGVsbG8gd29ybGQ=,ff_U2ltU3Vu,sz_26,fc_0000007f,g_9,x_70,y_50 |