图片处理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中用来区分一些关键字段的分隔符号。

管道

如果一个图片，需要多重处理，如先裁剪、后缩略等，则多组操作命令之间，需要以管道“|”连接，执行顺序按管道指定顺序从左至右执行。

例如：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。

图片处理命令

图片缩放、旋转、渐进显示

命令参数

注意事项：

• 当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

  

图片裁剪

命令参数

示例

• 以图片左上角横坐标为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个区域，并按照图示位置进行编号，每个区域的锚点位置如图所示：

确定水印在原图上的最终位置，您需要确定如下两个因素：

1. 锚点位置；
2. 基于锚点位置，指定在水平和垂直方向上的距离。

图片水印

命令参数

说明

水印图片要与原始图片存储在BOS的同一个Bucket下。

示例

原图为image.jpg，水印图片为bce-documentation/BOS/bce.jpg(Base64编码后为“YmNlLWRvY3VtZW50YXRpb24vQk9TL2JjZS5qcGc=”)。

• 在右下角加上图片水印，指定垂直距离为10，透明度为60。

  https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@wm_1,k_YmNlLWRvY3VtZW50YXRpb24vQk9TL2JjZS5qcGc=,y_10,o_60

  

• 在左下角加上水印，水平和垂直距离取缺省值，透明度为50，并顺时针旋转90度。

  https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@wm_1,k_YmNlLWRvY3VtZW50YXRpb24vQk9TL2JjZS5qcGc=,g_7,o_50,a_90

  

文字水印

命令参数

已支持的字体类型：

说明：

• 只有当fontFamily支持fontStyle效果时，才会渲染文字效果。
• 若指定的字体样式不在当前已支持的fontFamily列表中，则显示效果为默认字体宋体。

示例

• 最简单的文字水印，文字内容为“hello world”。

  https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@wm_2,t_aGVsbG8gd29ybGQ=

  

• 文字内容为“hello world”，字体类型为微软雅黑，字体颜色和字体大小取默认值，字体样式为粗体，水印位置在右中，距离锚点水平距离20，垂直距离20，并顺时针旋转30度。

  https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@wm_2,t_aGVsbG8gd29ybGQ=,ff_TWljcm9zb2Z0WWFIZWk=,fs_bold,g_6,x_20,y_20,a_30

  

图文混合水印

图文混合水印是指将图片水印和文字水印同时打在原始图片上。

由于图片水印和文字水印为两组独立的命令，因此图文混合水印需要用管道实现。

示例

• 最简单的图文混合水印：图片为bce-documentation/BOS/bce.jpg，文字内容为“hello world”，其余参数均取默认值。

  https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@wm_1,k_YmNlLWRvY3VtZW50YXRpb24vQk9TL2JjZS5qcGc=|wm_2,t_aGVsbG8gd29ybGQ=

  

• 图文混合水印：水印图片为bce-documentation/BOS/bce.jpg，位于原图左下角，距离锚点水平距离为,15，垂直距离为20，透明度为50；文字内容为“hello world”，位于正上方，垂直距离为100，字体颜色为淡紫色。

  https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@wm_1,k_YmNlLWRvY3VtZW50YXRpb24vQk9TL2JjZS5qcGc=,g_7,x_15,y_20,o_50|wm_2,t_aGVsbG8gd29ybGQ=,g_2,y_100,fc_aa88aa

  

获取图片信息

此命令用来获取图片信息，如果图片有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。

  https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@c_1,x_10,y_20,w_600,h_300|s_1,w_200,h_200,q_60,f_png

  

• 图文混合水印：水印图片为bce-documentation/BOS/bce.jpg，位于原图左下角，距离锚点水平距离为,15，垂直距离为20，透明度为50；文字内容为“hello world”，位于正上方，垂直距离为100，字体颜色为淡紫色。

  https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@wm_1,k_YmNlLWRvY3VtZW50YXRpb24vQk9TL2JjZS5qcGc=,g_7,x_15,y_20,o_50|wm_2,t_aGVsbG8gd29ybGQ=,g_2,y_100,fc_aa88aa

  

图片样式

图片样式是指您可以将一些常用的图片处理操作保存为一个别名，即一个样式。这样，一组复杂的操作，利用样式，可以通过一个简洁的URL访问即可达到相同效果。

访问方式

图片样式的访问方式为：http://${userdomain}/${objectkey}@!${stylename}，其中stylename为您定义的样式名称。

例如：您定义了一个名为“small”的样式，您的域名为51mingxi.com，您的图片名称为image.jpg，则您通过样式访问该图片的URL为http://51mingxi.com/image.jpg@!small。

添加样式

您可以通过控制台进行图片样式的定义，同时还可以在定义的同时实时进行效果预览。

1. 登录BOS控制台，进入您已开通图片服务的Bucket。点击左侧导航“图片服务”后，点击右侧页面中的“样式管理”。

2. 点击“添加样式”，进入添加样式表单页面。您可根据需要，设定该样式的图片处理参数，同时您可在右侧的预览区域实时进行效果预览。

   图片样式的设置方式支持“基础设置”和“高级设置”两种。

   • 基础设置，您需要在页面上对下方的每一项处理参数进行手动设定。
   • 高级设置，您可直接在框中直接输入图片处理命令参数。

   创建好样式后，点击“保存”。

   缩放说明

   • 限定宽度，高度等比例。

     您需要输入宽度，缩略时以宽度为基准，将高度等比例缩小。若输入宽度大于原图宽度，则返回原图。

     例如：原图宽高尺寸为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。

3. 保存样式后，在列表中可以看到您已经添加的样式信息。您可以点击“查看命令”，查看样式对应的参数命令。

   

删除样式

在样式管理列表中，点击“操作”列的“删除”，可删除样式。

示例

例如定义了如下样式：

• 使用参数命令访问：

  https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@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

  

• 使用样式访问：

  https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@!small