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

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

URL格式

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

或者

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

举例

例如：原始图片在云存储中的url为：http://ss.bscstorage.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
information i 信息类型 按照指定的类型获取图片信息
exif exif i_exif, 返回json格式的图片exif信息
iptc iptc i_iptc, 返回json格式的图片iptc信息
all all i_all, 返回json格式的图片全部信息

使用AWS-SDK访问图片处理服务

可以使用标准的AWS-SDK直接访问图片处理服务，注意imgx服务只接受标准的get_object操作，其他操作都是非法的。

下面的示例代码使用python boto3 sdk：

import boto3

s2_imgx_domain_name = 'http://imgx-ss.bscstorage.com'   # 示例使用三副本集群配置，此处需要根据不同集群进行调整
s2_imgx_access_key = 'xxxxxx'                           # 用户自己的access key
s2_imgx_secret_key = 'xxxxxx'                           # 用户自己的secret key

imgx_cmd = 'c_scale,w_100,h_100' # 图片处理命令，参考 图片处理指令 部分
imgx_bucket = 'my_imgx_bucket'   # 用户在存储上的bucket名称
imgx_key = 'my_img.jpg'          # 用户想要操作的图片的key名称


# 创建s2 client
imgx_cli = boto3.client('s3',
                        endpoint_url=s2_imgx_domain_name,
                        aws_access_key_id=s2_imgx_access_key,
                        aws_secret_access_key=s2_imgx_secret_key)

imgx_cmd_key = u'{cmd}/{key}'.format(cmd=imgx_cmd, key=imgx_key) # 作为最终访问时的Key
resp = imgx_cli.get_object(Bucket=imgx_bucket, Key=imgx_cmd_key)

print resp

水印功能详细介绍

  1. 水印分为：图片水印 和 文字水印；
  2. 如果您使用了水印 l 指令，则和 l 一组的其他指令将针对 水印图片或者文字 进行处理（如：w、h、g、x、y、o、bo、e、a、r等），后面举例介绍。

图片水印

您需要预先将水印贴图保存到对应的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 ""