Imgx(图片处理服务)使用说明

标签: 图片处理 imgx 白山云 存储服务


URL格式

http://imgx-ss.bscstorage.com/<bucket>/<处理指令>/<文件路径>?<签名保护>

或者

http://<bucket>.imgx-ss.bscstorage.com/<处理指令>/<文件路径>?<签名保护>
  • bucket : 您在云存储服务中的bucket名称;
  • 处理指令 : 对原始图片的处理指令,下面有详细介绍;
  • 文件路径 : 原始图片文件在云存储服务中的存储路径;
  • 签名保护 : 主要是签名相关的参数;

举例

例如:原始图片在云存储中的url为:http://s2.i.qingcdn.com/imgx-test/demo/1.jpg?AWSAccessKeyId=acc_drdrxp&Expires=2464773061&Signature=jFVHRSrOLeg5e3nIR00UE2vik0A%3D 可以看出:

  • bucket为:imgx-test
  • 在bucket中的路径为:demo/1.jpg

下面我们进行下列操作:

  • 裁剪人脸区域, 并将图片缩略:400x400:c_thumb,g_face,w_400,h_400
  • 将图片变成圆角,半径为最大(正圆):r_max
  • 将图片亮度增加8%:e_brightness:8
  • 将图片格式转换为png格式:f_png

处理指令为:c_thumb,g_face,w_400,h_400,r_max,e_brightness:8,f_png 我们可以通过URL直接进行访问:

http://imgx-ss.bscstorage.com/imgx-test/c_thumb,g_face,w_400,h_400,r_max,e_brightness%3A8,f_png/demo/1.jpg?AWSAccessKeyId=acc_drdrxp&Expires=2464773122&Signature=4cwxt1e%2Fg2NL1OfsldaVsa8SD9s%3D

或者

http://imgx-test.imgx-ss.bscstorage.com/c_thumb,g_face,w_400,h_400,r_max,e_brightness%3A8,f_png/demo/1.jpg?AWSAccessKeyId=acc_drdrxp&Expires=2464773122&Signature=4cwxt1e%2Fg2NL1OfsldaVsa8SD9s%3D

或者创建一个json文件(如果您不想将处理指令暴露在URL中),内容为:

[
    {
        "crop" : "thumb",
        "gravity" : "face",
        "width" : 400,
        "height" : 400,
        "radius" : "max",
        "effect" : "brightness:8",
        "format" : "png"
    }
]

将文件保存到您对应的bucket下的路径:

imgx/cmd_template/my_thumb.json    #其中文件名(my_thumb)是您自定义的“指令集名称”,类似css中的class

然后就可以通过下面的URL进行访问(也就是说,处理指令也可以不用放在URL中,直接隐藏到您自定义的json文件中):

http://imgx-ss.bscstorage.com/imgx-test/t_my_thumb/demo/1.jpg?AWSAccessKeyId=acc_drdrxp&Expires=2464773563&Signature=WIMaNLacGaPRAlA6fl%2BGAsStfoQ%3D

指令格式

  • 指令名和指令值之间用“_”连接,如:c_fit
  • 相关指令使用逗号隔开“,” 如: c_fit,w_100,h_100,g_face
  • 多组指令之间用“--”隔开,如: c_fit,w_100,h_100,g_face,r_max--l_text:my_font:hello+word,w_100,h_40

签名

为了保护您的原图不被盗取以及处理指令不被恶意滥用,所以这里必须使用签名保护,签名形式完全兼容AWS-V2认证,以下提供一个生成代签名URL的php函数:

/**
* Get a query string authenticated URL
*
* @param string $accessKey AccessKey
* @param string $secretKey SecretKey
* @param string $bucket Bucket name
* @param string $uri Object URI
* @param integer $lifetime Lifetime in seconds
* @param boolean $hostBucket Use the bucket name as the hostname
* @param boolean $https Use HTTPS ($hostBucket should be false for SSL verification)
* @return string
*/
function getAuthenticatedURL($accessKey, $secretKey, $bucket, $uri, $lifetime, $hostBucket = false, $https = false, $endpoint = 'imgx-ss.bscstorage.com') {

    $expires = time() + $lifetime;
    $uri = str_replace(array('%2F', '%2B', '%2C', '%3A', '%20'), array('/', '+', ',', ':', '+'), rawurlencode($uri));
    return sprintf(($https ? 'https' : 'http').'://%s/%s?AWSAccessKeyId=%s&Expires=%u&Signature=%s',
    $hostBucket ? $bucket : $endpoint.'/'.$bucket, $uri, $accessKey, $expires,
    urlencode(base64_encode(hash_hmac('sha1', "GET\n\n\n{$expires}\n/{$bucket}/{$uri}", $secretKey, true))));
}
//用法很简单
echo getAuthenticatedURL('您的accessKey', '您的secretKey', '您的bucket', '指令/文件路径', '多久以后过期(秒)');
# 建议$lifetime设置比较长,例如:1000000000

缓存 & CDN

  • 处理后的图片生成缓存,下次请求不在重复生成,默认缓存2天
  • 如果配置了CDN,处理后的图片会自动推送到CDN节点

图片处理指令

以下介绍具体处理指令,用下列几张原图为例,方便您对照:

  1. demo/charles.png
  2. demo/1.jpg
  3. demo/3.png
  4. demo/4.png
  5. demo/sheep.png
  6. demo/horses.png
  7. avatar.png
指令名 指令 Value 示例 描述
crop c mode 裁剪方式,指定图像裁剪或放缩的方式。
scale 改变图像的大小,以匹配给定的宽度和高度。所有原始图像的部分将是可见的,但可能会被拉伸而变形。

c_scale,h_80,w_80
fill 裁剪图像,同时保留原有比例。

c_fill,h_80,w_80
lfill fill 模式,不同的是限制图片尺寸不大于原图

c_lfill,h_80,w_80
fit 改变图像的大小,以匹配给定的宽度和高度,同时保留原有比例,所有原始图像的部分将是可见的。等比放缩,不会因为拉伸而变形。

c_fit,h_80,w_80
mfit fit 模式,不同的是限制图片尺寸不小于原图

c_mfit,h_80,w_80
limit fit,不同的是限制图片尺,处理后的图片尺寸不会超过原图。

c_limit,h_80,w_80
pad 指定图像的尺寸,同时保留原有比例。如果原图比例不满足指定的尺寸,将被填充为背景颜色。

c_pad,h_80,w_80,g_center,b_dddddd
lpad pad 模式,不同的是,如果指定的尺寸大于原图,将不扩大原图

c_lpad,h_640,w_640,g_center,b_dddddd
mpad pad 模式,不同的是限制图片尺寸不小于原图

c_mpad,h_80,w_80,g_center,b_dddddd
crop 指定尺寸和位置,用于从原始图片的基础上裁剪出一部分。

c_crop,h_210,w_210,g_face
thumb 定位人脸(结合'face'或'faces'重力参数)并生成缩略图,常用于生成头像。

c_thumb,h_250,w_250,g_face
width w 像素或者百分比 宽度参数,结合 裁剪方式(crop) 或者 水印(overlay) 使用
80 调整宽度为80像素

w_80
0.1 调整图像到其原始尺寸的10%。

w_0.1
height h 像素或者百分比 高度参数,结合 裁剪方式(crop) 或者 水印(overlay) 使用
80 调整高度为80像素

h_80
0.1 调整图像到其原始尺寸的10%。

h_0.1
gravity g 用于指定位置或者方向 1. 用于 'crop', 'pad', 'fill' 的裁剪方式;
2. 用于指定 水印(overlay) 的位置
north_west 左上位置

c_crop,g_north_west,h_200,w_200
north 正上位置,水平方向居中

c_crop,g_north,h_200,w_200
north_east 右上位置

c_crop,g_north_east,h_200,w_200
west 左边,垂直方向居中

c_crop,g_west,h_200,w_200
center 正中

c_crop,g_center,h_200,w_200
east 右边,垂直方向居中

c_crop,g_east,h_200,w_200
south_west 左下位置

c_crop,g_south_west,h_200,w_200
south 正下位置,水平方向居中

c_crop,g_south,h_200,w_200
south_east 右下位置

c_crop,g_south_east,h_200,w_200
xy_center 指定的x,y坐标,并作为中心点

c_crop,g_xy_center, h_400,w_400,x_245,y_240
face 自动定位人脸的位置,如果有多张脸,选择最容易识别的一个

c_crop,g_face,h_140,w_140
face (thumb) 自动定位人脸的位置,并且根据指定的尺寸生成缩略图。如果有多张脸,选择最容易识别的一个

c_thumb,g_face,h_130,w_140,f_png
faces 自动定位多张人脸的位置

c_thumb,g_faces,h_220,w_600, e_brightness:18
face:center 自动定位人脸的位置,如果找不到人脸则自动定位到原图的中心

c_thumb,g_face:center,h_140,w_140
faces:center 自动定位多张人脸的位置,如果找不到人脸则自动定位到原图的中心

c_thumb,g_faces:center, h_120,w_330,e_brightness:18
x x 像素 用于指定图片裁剪或者水印的横向坐标。
110 裁剪图像180x180像素,从左边110像素开始

c_crop,h_180,w_180,x_110
y y 像素 用于指定图片裁剪或者水印的纵向坐标。
230 裁剪图像180x180像素,从顶部230像素开始。

c_crop,h_180,w_180,x_180,y_230
quality q 百分比 控制JPG或者WEBP格式图片的压缩质量。最小值为1,最大值为100。
100 图片质量为100%,文件大小为14.3KB。

c_thumb,g_face,h_130,w_140,q_100
10 图片质量为10%,文件大小降低到1.5KB。

c_thumb,g_face,h_130,w_140,q_10
radius r 像素值或者'max' 指定半径,生成圆角或完全变成圆形(椭圆)。
30 生成30像素半径的圆角

c_thumb,g_face,h_140,w_140,f_png,r_30
max 使用最大半径生成圆角

c_thumb,g_face,h_140,w_140,f_png,r_max
angle a 角度或者翻转模式 翻转或者旋转图像
90 顺时针旋转90度

c_fill,h_80,w_80,a_90
10 顺时针旋转10度

c_fill,h_80,w_80,a_10
-20 逆时针旋转20度

c_fill,h_80,w_80,a_-20
vflip 垂直翻转

c_fill,h_80,w_80,a_vflip
hflip 水平翻转

c_fill,h_80,w_80,a_hflip
effect e name and value 使用滤镜或者特效
grayscale 灰度

c_fill,h_380,w_380,e_grayscale
oil_paint 油画效果

c_fill,h_380,w_380,e_oil_paint
oil_paint:2 使用油画效果,并指定一个level值为2,取值范围1到8,默认值为4

c_fill,h_380,w_380,e_oil_paint:2
negate 反色

c_fill,h_380,w_380,e_negate:2
brightness:28 调整图片的亮度,并指定一个百分比值为28,取值范围-100到100,默认值为30

c_fill,h_380,w_380,e_brightness:28
brightness:-28 调整图片的亮度,并指定一个百分比值为-20,取值范围-100到100,默认值为30

c_fill,h_380,w_380,e_brightness:-20
blur 模糊效果

c_fill,h_380,w_380,e_blur
blur:300 使用模糊效果,并指定一个level值为300,取值范围1到2000,默认值为100

c_fill,h_380,w_380,e_blur:300
pixelate 像素化

c_fill,h_380,w_380,e_pixelate:20
pixelate:40 使用像素化效果,并指定一个level值为40,默认值为5

c_fill,h_380,w_380,e_pixelate:40
sharpen 锐化

c_fill,h_380,w_380,e_sharpen
sharpen:400 使用锐化效果,并指定一个level值为400,取值范围1到2000,默认值为100

c_fill,h_380,w_380,e_sharpen:400
auto_contrast 自动对比度

c_fill,h_380,w_380,e_auto_contrast
improve 自动调整图像色彩,对比度和亮度。

c_fill,h_380,w_380,e_improve
sepia 增加褐色,实现老照片效果

c_fill,h_380,w_380,e_sepia
sepia:60 增加褐色,实现老照片效果,并指定一个level值为60。取值范围1到100,默认值为80。

c_fill,h_380,w_380,e_sepia:60
red:40 增加红色

c_fill,h_380,w_380,e_red:40
green:40 增加绿色

c_fill,h_380,w_380,e_green:40
blue:40 增加蓝色

c_fill,h_380,w_380,e_blue:40
yellow:40 增加黄色

c_fill,h_380,w_380,e_yellow:40
cyan:40 增加青色

c_fill,h_380,w_380,e_cyan:40
magenta:40 增加粉色

c_fill,h_380,w_380,e_magenta:40
opacity o 百分比 控制PNG或者WEBP格式图片不透明度。最小值为1,最大值为100。
25 不透明度为25%

h_330,w_330,o_25
border bo style 设置边框
10_0000004a 设置一个边框宽度为10px,颜色值为黑色,透明度为4a(16进制)

h_330,w_330,bo_10_0000004a
8_bbbbbb 对圆角图像设置一个边框宽度为8px,颜色值为bbbbbb

h_330,w_330,bo_8_bbbbbb,r_100
background b color 设置背景颜色,配合其他指令
dddddd 设置背景颜色为dddddd

c_pad,w_380,h_180,b_dddddd
fff6def0 设置背景颜色为fff6de,透明度为f0 (16进制)

c_fill,h_110,w_110,a_30,b_fff6def0
dbeced 设置背景颜色为dddddd

c_fill,h_140,w_140,r_max,b_dbeced--c_lpad,g_center,w_152,h_152,b_dbeced
overlay l 水印图片名,或者字体描述文件名称等 在原图上增加水印。您可以配合w,h,x,y和重力参数控制水印的尺寸和位置,还可以使用o参数控制水印的透明度
superman 在图片的右下角加一个方脸超人的水印(支持外部区域);首先需要将水印贴图(必须是png格式)保存到您的对应bucket下,路径规则为:imgx/overlay/my_name.png,然后您可以使用l_my_name指令进行水印操作了

c_fill,w_500,h_500,g_face, f_png--l_superman,g_south_east, w_250,x_-120,y_-60--l_scs_logo,x_20,y_20
text:font_me:你好,白山云 文字水印。关于字体样式的设置后面会详细介绍。

l_text:font_me:你好,白山云, g_north_east,x_14,y_14--w_400
format f 图片格式 图片格式转
png f_png
webp f_webp
jpeg f_jpeg
jpg f_jpg
version v 版本 缓存未过期的情况下指定版本重新生成图像
1.21 小数 v_1.21
13 整数 v_13
transformation t 名称 "指令集",指令可以不放到URL中,使用json格式的文件,保存到指定的路径下
my_thumbs 自定义名称,在对应的bucket下,创建文件:imgx/cmd_template/my_thumbs.json

t_my_thumbs

水印功能详细介绍

  1. 水印分为:图片水印文字水印
  2. 如果您使用了水印 l 指令,则和 l 一组的其他指令将针对 水印图片或者文字 进行处理(如:whgxyoboear等),后面举例介绍。

图片水印

您需要预先将水印贴图保存到对应的bucket下 imgx/overlay/<filename>.png,图片必须是png格式,下面两张图为例:

水印贴图 对应路径 对应指令
imgx/overlay/icon_v.png l_icon_v
imgx/overlay/bs_logo.png l_bs_logo

下面举例介绍具体功能

示例 描述 指令
1. 将原图等比放缩;
2. 添加一个图片水印到原图的左上角,并且微调坐标(x_43,y_20),设置水印的宽度为120px,不透明度为35%,逆时针旋转水印10度
c_fit,w_300,f_png-- l_bs_logo,g_north_west, w_120,o_35,x_43,y_20,a_-10
1. 将原图处理成一个圆角头像;
2. 在右下角添加一个水印图片,并且向外微调水印坐标(x_-1,y_-5),设置水印图片的宽度为60px
c_thumb,g_face,w_200,h_200, r_max,bo_6_ffffff80,f_png--l_icon_v, g_south_east,w_60,x_-1,y_-5
1. 同上
2. 将水印图片反色
c_thumb,g_face,w_200,h_200, r_max,bo_6_ffffff80,f_png--l_icon_v, g_south_east,w_60,x_-1,y_-5,e_negate


文字水印

您需要预先将文字水印的字体配置(json格式的文件)保存到对应的bucket下 imgx/overlay/<file>.json,例如:

{
    "font_family" : "Xingkai SC",
    "font_style" : "bold",
    "font_size" : 30,
    "font_color" : "000000",
    "background" : "ff0000cc",
    "padding" : 10,
    "word_spacing" : 1,
    "kerning" : 1,
    "line_spacing" : 2,
    "pierced" : false,
    "tile" : false,
    "text" : "默认值",
}

对应路径:imgx/overlay/my_font.json

字体参数介绍

所有参数非必填项

参数名 介绍 默认值
font_family 字体家族,我们支持的所有 字体 Songti SC
font_style 字体样式(如果字体本身支持以下样式才有效果,否则默认使用normal):
     normal(常规)
     italic(斜体)
     bold(粗体)
     light(细体)
normal
font_size 字号(单位:px) 14
font_color 16进制rgba(前6为rgb,最后2位alpha,都是0到f),省略最后两位则认为不透明 黑色(000000)
background 16进制rgba(前6为rgb,最后2位alpha,都是0到f),省略最后两位则认为不透明 透明(ffffff00)
padding 文字周围填充的宽度(单位:px) 6
word_spacing 词间距(单位:px) 0
kerning 字间距(单位:px) 0
line_spacing 行间距(单位:px) 0
pierced 镂空字效果(bool值) false
tile 是否平铺(bool值) false
text 默认字符串 空字符串

示例1:

imgx/overlay/simple_font.json :

{
    "font_family" : "Microsoft YaHei",
    "font_size" : 40,
    "font_color" : "ffffff"
}

一个最简单的文字水印

指令:

w_800,f_png--l_text:simple_font:Hello+Bai+Shan!!,x_20,y_20,a_-25

示例2:

imgx/overlay/subtitles.json :

{
    "font_size" : 22,
    "font_color" : "ffffff"
}

imgx/overlay/subtitles_s.json :

{
    "font_size" : 16,
    "font_color" : "ffffff"
}

咱们也搞一个大片效果, 应用到两张图上:

指令:

f_png,c_fill,w_800,h_400,e_brightness:-8--c_pad,w_800,h_550,g_center,b_000000ff,e_yellow:30--l_text:subtitles:为开发者提供一套云端图片处理服务,g_south,y_100--l_text:subtitles_s:Imgx is the image back-end for web and mobile developers,g_south,y_80

示例3:

imgx/overlay/my_font.json :

{
    "font_family" : "Xingkai SC",
    "font_style" : "bold",
    "font_size" : 40,
    "font_color" : "000000",
    "background" : "ff0000cc",
    "padding" : 18
}

咱们做一个对联:

指令:

w_800,f_png--l_text:my_font:马驰大道征途远,g_south_west,w_40,x_20,y_100--l_text:my_font:羊上奇峰景色娇,g_south_east,w_40,x_20,y_100--l_text:my_font:图片处理,g_north,y_20

示例4:

imgx/overlay/font_me.json :

{
    "font_family": "Microsoft YaHei",
    "font_size": 30,
    "font_color": "ffffff",
    "font_style": "bold",
    "background": "0000008f",
    "pierced": true,
    "tile": false,
    "padding": 12,
    "word_spacing": 2.2,
    "line_spacing": 1.2,
    "kerning": 1.5
}

镂空字效果

指令:

l_text:font_me:你好,白山云,g_north_west,x_20,y_20--w_800

示例5:

imgx/overlay/tile.json :

{
    "font_family" : "Microsoft YaHei",
    "font_style" : "bold",
    "font_size" : 40,
    "font_color" : "000000",
    "background" : "ff000066",
    "padding" : 18,
    "tile": true
}

平铺效果

指令:

w_800,f_png--l_text:tile:Hello BaiShan!!,g_south

示例6:

imgx/overlay/badge.json :

{
    "font_style" : "bold",
    "font_size" : 30,
    "font_color" : "ffffff",
    "background" : "ff0000cc",
    "padding" : 15
}

增加一个badge(数字徽章)

指令:

c_thumb,g_face,w_200,h_200,r_max,bo_6_ffffff80,f_png--l_text:badge:69,r_max,g_south_east,w_34,h_34,x_-1,y_-5

使用“指令集”

如果您不希望把指令暴露在URL中,很简单:

下面举例说明,自动识别照片上的人脸位置并做一张带有边框的圆形缩略图:

  • 先创建一个json文件,保存到对应的bucket中: 路径: imgx/cmd_template/avatar.json

    [
      {
          "crop" : "thumb",
          "gravity" : "face:center",
          "width" : 200,
          "height" : 200,
          "radius" : "max",
          "border" : "6_ffffff80",
          "format" : "png"
      },
      {
          "overlay" : "icon_v",
          "gravity" : "south_east",
          "width" : 60,
          "x" : -1,
          "y" : -5
      }
    ]
    
  • 通过下面的方式访问:

http://imgx-ss.bscstorage.com/imgx-test/t_avatar/demo/1.jpg?<签名>
http://imgx-ss.bscstorage.com/imgx-test/t_avatar/demo/3.jpg?<签名>
  • 效果:

字体 (font_family)

查询字体的API:http://imgx-ss.bscstorage.com/fonts

results matching ""

    No results matching ""