简介

腾讯云对象存储（Cloud Object Storage，COS）集成了 数据万象（Cloud Infinite，CI）专业的一体化多媒体解决方案，涵盖以下图片处理功能，详情可见 图片处理概述。

服务	功能	说明
基础图片处理服务	缩放	等比缩放、设定目标宽高缩放等多种方式
	裁剪	普通裁剪、缩放裁剪、内切圆、人脸智能裁剪
	旋转	自适应旋转、普通旋转
	格式转换	格式转换、GIF 格式优化、渐进显示
	质量变换	针对 JPG 和 WEBP 图片进行质量变换
	高斯模糊	对图片进行模糊处理
	亮度	调节图片亮度
	对比度	调节图片对比度
	锐化	对图片进行锐化处理
	添加水印	图片水印、文字水印
	获取图片信息	基本信息、EXIF 信息、主色调
	去除元信息	包括 EXIF 信息
	快速缩略模板	快速实现图片格式转换、缩略、剪裁等功能，生成缩略图
	管道操作符	实现对图片按顺序进行多种处理

实例化 Template

在使用基础图片处理功能时，首先实例化 Template 类，调用方法生成万象图片处理参数后，获取文件资源时传入，下面所有操作一致，不再重复说明。

示例代码

try {
      $imageMogrTemplate = new Qcloud\Cos\ImageParamTemplate\ImageMogrTemplate();//创建基础图片处理参数模版实例
      $imageMogrTemplate->thumbnailByScale(50);//指定图片的宽高为原图的 50%
      $result = $cosClient->getObject(array(
      'Bucket' => 'examplebucket-1250000000', //格式：BucketName-APPID
      'Key' => 'exampleobject',
      'ImageHandleParam' => $imageMogrTemplate->queryString(),//生成基础图片处理参数
  ));
  // 请求成功
  print_r($result);
} catch (\Exception $e) {
  // 请求失败
  echo($e);
}

参数说明

参数名称	类型	描述	是否必填
Bucket	String	存储桶名称，格式：BucketName-APPID	是
Key	String	此处的 Key 为对象键，对象键是对象在存储桶中的唯一标识。例如，在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中，对象键为doc/pic.jpg	是
ImageHandleParam	String	万象图片处理参数，例如：imageMogr2/thumbnail/!50p	是

返回结果示例

Guzzle\Service\Resource\Model Object
(
  [structure:protected] => 
  [data:protected] => Array
      (
          [Body] => 
          [RequestId] => NWQwOGRkNDdfMjJiMjU4NjRfNzVjXzEwNmVjY2M=
          [ContentLength] => 100
          [CacheControl] => max-age=2592000
          [ContentType] => image/jpeg
          [Key] => exampleobject
          [Bucket] => examplebucket-1250000000
          [Location] => examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject
      )
)

返回结果说明

参数名称	类型	描述	父节点
Body	File/String	下载内容	无
RequestId	String	请求 ID 标识	无
CacheControl	String	缓存策略，设置 Cache-Control	无
ContentType	String	内容类型，设置 Content-Type	无
ContentLength	Int	响应体长度	无
Key	String	对象键	无
Bucket	String	存储桶名称，格式：BucketName-APPID	无
Location	String	请求资源地址	无

缩放

按百分比缩放

$imageMogrTemplate->thumbnailByScale(50);//指定图片的宽高为原图的 50%
$imageMogrTemplate->thumbnailByWidthScale(50);//指定图片的宽为原图的 50%，高度不变
$imageMogrTemplate->thumbnailByHeightScale(50);//指定图片的高为原图的 50%，宽度不变

指定宽高缩放

$imageMogrTemplate->thumbnailByWidth(50);//指定目标图片宽度为50，高度等比压缩
$imageMogrTemplate->thumbnailByHeight(50);//指定目标图片高度为50，宽度等比压缩
$imageMogrTemplate->thumbnailByMaxWH(50, 50);//限定缩略图的宽度和高度的最大值分别为50和50，进行等比缩放
$imageMogrTemplate->thumbnailByMinWH(50, 50);//限定缩略图的宽度和高度的最小值分别为50和50，进行等比缩放
$imageMogrTemplate->thumbnailByWH(50, 50);//忽略原图宽高比例，指定图片宽度为50，高度为50 ，强行缩放图片，可能导致目标图片变形

等比缩放

$imageMogrTemplate->thumbnailByPixel(1000);//等比缩放图片，缩放后的图像，总像素数量不超过1000

裁剪

普通裁剪

$imageMogrTemplate->cut(100, 300, 30, 30);//指定目标图片宽度、高度、相对于图片左上顶点水平向右偏移、相对于图片左上顶点水平向下偏移进行裁剪

缩放裁剪

方位图说明，请参见 九宫格方位图。

$imageMogrTemplate->cropByWidth(100);//按照指定目标宽度进行缩放裁剪
$imageMogrTemplate->cropByWidth(100, 'center');//按照指定目标宽度进行缩放裁剪，指定操作的起点位置
$imageMogrTemplate->cropByHeight(100);//按照指定目标高度进行缩放裁剪
$imageMogrTemplate->cropByHeight(100, 'center');//按照指定目标高度进行缩放裁剪，指定操作的起点位置
$imageMogrTemplate->cropByWH(100, 100);//按照指定目标宽度和高度进行缩放裁剪
$imageMogrTemplate->cropByWH(100, 100, 'center');//按照指定目标宽度和高度进行缩放裁剪，指定操作的起点位置

内切圆裁剪

radius 是内切圆的半径，取值范围为大于0且小于原图最小边一半的整数。内切圆的圆心为图片的中心。图片格式为 GIF 时，不支持该操作。

$imageMogrTemplate->iradius(100);//指定半径100为例

圆角裁剪

radius 为图片圆角边缘的半径，取值范围为大于0且小于原图最小边一半的整数。圆角与原图边缘相切。图片格式为 GIF 时，不支持该操作。

$imageMogrTemplate->rradius(1000);// 指定圆角半径100为例

人脸智能裁剪

基于图片中的人脸位置进行缩放裁剪。目标图片的宽度为 Width、高度为 Height。

$imageMogrTemplate->scrop(100, 100);// 裁剪人脸并宽高指定100缩放为例；

旋转

普通旋转

图片顺时针旋转角度，取值范围0 - 360，默认不旋转。

$imageMogrTemplate->rotate(45);//以旋转45度为例

自适应旋转

根据原图 EXIF 信息将图片自适应旋转回正。

$imageMogrTemplate->autoOrient();

格式转换

普通转换

目标缩略图的图片格式可为：jpg，bmp，gif，png，webp，yjpeg 等，其中 yjpeg 为针对 jpeg 格式进行的优化，本质为 jpg 格式；缺省为原图格式。

$imageMogrTemplate->format('png');//格式转换png

GIF 格式优化

该功能只针对原图为 gif 格式，对 gif 图片格式进行的优化，降帧降颜色。分为以下两种情况：

• FrameNumber=1，则按照默认帧数30处理，如果图片帧数大于该帧数则截取。
• FrameNumber 取值( 1,100 ]，则将图片压缩到指定帧数 （FrameNumber）。

$imageMogrTemplate->gifOptimization(50);//压缩到指定帧数50

输出渐进式 JPG 格式

该操作仅在输出图片格式为 jpg 格式时有效。如果输出非 jpg 图片格式，会忽略该参数。取值范围0或1，0：表示不开启渐进式；1：开启渐进式，默认值0。

$imageMogrTemplate->jpegInterlaceMode(1);//开启渐进式。

质量变换

质量变换功能提供三种变换类型：绝对变换、相对变换、最低质量变换，可调节图片质量。该功能仅适用于 JPG 和 WEBP 格式的图片。

绝对变换

设置图片的绝对质量，取值范围0 - 100，默认值为原图质量；取原图质量和指定质量的最小值。
是否强制使用指定值，取值范围0或1，0：表示不强制使用；1：表示强制使用，默认值0。

$imageMogrTemplate->quality(90, 1);//强制指定质量90

相对变换

设置图片的相对质量，取值范围0 - 100，数值以原图质量为标准。例如原图质量为80，将 rquality 设置为80后，得到处理结果图的图片质量为64（80x80%）。

$imageMogrTemplate->relativelyQuality(80);

最低质量变换

图片的最低质量，取值范围为0 - 100，设置结果图的质量参数最小值。

• 例如原图质量为85，将 lquality 设置为80后，处理结果图的图片质量为85。
• 例如原图质量为60，将 lquality 设置为80后，处理结果图的图片质量会被提升至80。

$imageMogrTemplate->lowestQuality(90);

高斯模糊

高斯模糊功能，模糊半径，取值范围为1 - 50；正态分布的标准差，必须大于0。图片格式为 gif 时，不支持该参数。

$imageMogrTemplate->blur(20, 20);// 模糊半径20，正态分布的标准差20为例

亮度

图片亮度调节功能，取值范围为[-100, 100]的整数。

//取值＜0：降低图片亮度。
//取值 = 0：不调整图片亮度。
//取值＞0：提高图片亮度。
$imageMogrTemplate->bright(50);// 提高图片亮度50

对比度

图片对比度调节功能，取值范围为[-100, 100]的整数。

//取值＜0：降低图片对比度。
//取值 = 0：不调整图片对比度。
//取值＞0：提高图片对比度。
$imageMogrTemplate->contrast(50);// 提高图片对比度50

锐化

图片锐化功能，取值范围为10 - 300间的整数，推荐使用70。参数值越大，锐化效果越明显。

$imageMogrTemplate->sharpen(70);// 以锐化值70为例

添加水印

方位图说明，请参见 九宫格方位图。

图片水印

指定的水印图片必须同时满足如下3个条件：

1. 水印图片与源图片必须位于同一个存储桶下。
2. URL 需使用 COS 域名（不能使用 CDN 加速域名，例如 examplebucket-1250000000.file.myqcloud.com/shuiyin_2.png 不可用），且需保证水印图可访问。如果水印图读取权限为私有，则需要携带有效签名。
3. URL 必须以http://开始，不能省略 HTTP 头，也不能填 HTTPS 头，例如 examplebucket-1250000000.cos.ap-shanghai.myqcloud.com/shuiyin_2.png，https://examplebucket-1250000000.cos.ap-shanghai.myqcloud.com/shuiyin_2.png 为非法的水印 URL。

try {
      $imageWatermarkTemplate = new Qcloud\Cos\ImageParamTemplate\ImageWatermarkTemplate();//创建图片水印参数模版实例
      $imageWatermarkTemplate->setImage("imageurl");//设置水印图片地址
      $imageWatermarkTemplate->setGravity('center');//设置水印九宫格位置
      $imageWatermarkTemplate->setDx(10);//设置水平（横轴）边距
      $imageWatermarkTemplate->setDy(10);//设置垂直（纵轴）边距
      $imageWatermarkTemplate->setBlogo(1);//设置水印图适配功能，适用于水印图尺寸过大的场景（如水印墙）共有两种类型：设置为1时，水印图会被缩放至与原图相似大小后添加；设置为2时，水印图会被直接裁剪至与原图相似大小后添加。
      $imageWatermarkTemplate->setScatype(1);//根据原图大小调整水印图大小，1:按宽缩放，2:按高缩放，3:按面积缩放
      $imageWatermarkTemplate->setSpcent(100);//设置水印图片占原图的千分比为100/1000,取值范围为[1,1000]，默认为原水印图大小
      $result = $cosClient->getObject(array(
      'Bucket' => 'examplebucket-1250000000', //格式：BucketName-APPID
      'Key' => 'exampleobject',
      'ImageHandleParam' => $imageWatermarkTemplate->queryString(),//生成图片水印参数
  ));
  // 请求成功
  print_r($result);
} catch (\Exception $e) {
  // 请求失败
  echo($e);
}

文字水印

COS 提供实时文字水印处理功能。水印字体列表可参见 支持字体列表。字体颜色列表可参见 RGB 编码表。

try {
      $textWatermarkTemplate = new Qcloud\Cos\ImageParamTemplate\TextWatermarkTemplate();//创建文字水印参数模版实例
      $textWatermarkTemplate->setText("test");//设置水印内容
      $textWatermarkTemplate->setFont("tahoma.ttf");//设置水印字体,默认值 tahoma.ttf
      $textWatermarkTemplate->setFontsize(30);//设置水印文字字体大小，单位为磅，缺省值13
      $textWatermarkTemplate->setFill("#3D3D3D");//设置字体颜色，需设置为十六进制 RGB 格式（例如 #FF0000），默认值为 #3D3D3D(灰色)
      $textWatermarkTemplate->setDissolve(90);//设置文字透明度，取值1 - 100 ，默认90（完全不透明）
      $textWatermarkTemplate->setGravity('center');//设置文字水印位置，九宫格位置（参见九宫格方位图），默认值 southeast
      $textWatermarkTemplate->setDx(10);//设置水平（横轴）边距，单位为像素，缺省值为0
      $textWatermarkTemplate->setDy(10); //设置垂直（纵轴）边距，单位为像素，默认值为0
      $textWatermarkTemplate->setDegree(1);//设置平铺水印功能，可将文字水印平铺至整张图片。当设置为1时，开启平铺水印功能
      $textWatermarkTemplate->setBatch(45);//设置文字水印的旋转角度设置，取值范围为0 - 360，默认0
      $result = $cosClient->getObject(array(
      'Bucket' => 'examplebucket-1250000000', //格式：BucketName-APPID
      'Key' => 'exampleobject',
      'ImageHandleParam' => $textWatermarkTemplate->queryString(),//生成文字水印参数
  ));
  // 请求成功
  print_r($result);
} catch (\Exception $e) {
  // 请求失败
  echo($e);
}

获取图片信息

获取图片基本信息

查询图片基本信息。

示例代码

try {
      $result = $cosClient->ImageInfo(array(
      'Bucket' => 'examplebucket-1250000000', //格式：BucketName-APPID
      'Key' => 'exampleobject',
  ));
  // 请求成功
  print_r($result);
} catch (\Exception $e) {
  // 请求失败
  echo($e);
}

参数说明

参数名称	类型	描述	是否必填
Bucket	String	存储桶名称，格式：BucketName-APPID	是
Key	String	此处的 Key 为对象键，对象键是对象在存储桶中的唯一标识。例如，在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中，对象键为doc/pic.jpg	是

返回结果示例

Guzzle\Service\Resource\Model Object
(
  [structure:protected] => 
  [data:protected] => Array
      (
          [Body] => 
          [RequestId] => NWQwOGRkNDdfMjJiMjU4NjRfNzVjXzEwNmVjY2M=
          [ContentLength] => 100
          [ContentType] => application/json
          [Key] => exampleobject
          [Bucket] => examplebucket-1250000000
          [Location] => examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject
          [Data] => {"format": "jpeg", "width": "400", "height": "400"}
      )
)

返回结果说明

参数名称	类型	描述	父节点
Body	File/String	返回体	无
RequestId	String	请求 ID 标识	无
ContentType	String	内容类型，设置 Content-Type	无
ContentLength	Int	响应体长度	无
Key	String	对象键	无
Bucket	String	存储桶名称，格式：BucketName-APPID	无
Location	String	请求资源地址	无
Data	Json/String	图片基本信息	无

获取图片 EXIF

获取图片 EXIF 信息。如图片无 exif 信息，将返回{"error" : "no exif data"}。

示例代码

try {
      $result = $cosClient->ImageExif(array(
      'Bucket' => 'examplebucket-1250000000', //格式：BucketName-APPID
      'Key' => 'exampleobject',
  ));
  // 请求成功
  print_r($result);
} catch (\Exception $e) {
  // 请求失败
  echo($e);
}

参数说明

参数名称	类型	描述	是否必填
Bucket	String	存储桶名称，格式：BucketName-APPID	是
Key	String	此处的 Key 为对象键，对象键是对象在存储桶中的唯一标识。例如，在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中，对象键为doc/pic.jpg	是

返回结果示例

Guzzle\Service\Resource\Model Object
(
  [structure:protected] => 
  [data:protected] => Array
      (
          [Body] => 
          [RequestId] => NWQwOGRkNDdfMjJiMjU4NjRfNzVjXzEwNmVjY2M=
          [ContentLength] => 32
          [ContentType] => application/json
          [Key] => exampleobject
          [Bucket] => examplebucket-1250000000
          [Location] => examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject
          [Data] => {"error" : "no exif data"}
      )
)

返回结果说明

参数名称	类型	描述	父节点
Body	File/String	返回体	无
RequestId	String	请求 ID 标识	无
ContentType	String	内容类型，设置 Content-Type	无
ContentLength	Int	响应体长度	无
Key	String	对象键	无
Bucket	String	存储桶名称，格式：BucketName-APPID	无
Location	String	请求资源地址	无
Data	Json/String	图片 EXIF 信息	无

获取图片主色调

获取图片主色调信息。

示例代码

try {
      $result = $cosClient->ImageAve(array(
      'Bucket' => 'examplebucket-1250000000', //格式：BucketName-APPID
      'Key' => 'exampleobject',
  ));
  // 请求成功
  print_r($result);
} catch (\Exception $e) {
  // 请求失败
  echo($e);
}

参数说明

参数名称	类型	描述	是否必填
Bucket	String	存储桶名称，格式：BucketName-APPID	是
Key	String	此处的 Key 为对象键，对象键是对象在存储桶中的唯一标识。例如，在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中，对象键为doc/pic.jpg	是

返回结果示例

Guzzle\Service\Resource\Model Object
(
  [structure:protected] => 
  [data:protected] => Array
      (
          [Body] => 
          [RequestId] => NWQwOGRkNDdfMjJiMjU4NjRfNzVjXzEwNmVjY2M=
          [ContentLength] => 19
          [ContentType] => application/json
          [Key] => exampleobject
          [Bucket] => examplebucket-1250000000
          [Location] => examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject
          [Data] => {"RGB": "0x483519"}
      )
)

返回结果说明

参数名称	类型	描述	父节点
Body	File/String	返回体	无
RequestId	String	请求 ID 标识	无
ContentType	String	内容类型，设置 Content-Type	无
ContentLength	Int	响应体长度	无
Key	String	对象键	无
Bucket	String	存储桶名称，格式：BucketName-APPID	无
Location	String	请求资源地址	无
Data	Json/String	图片主色调信息	无

去除元信息

去除图片元信息，包括 EXIF 信息。

$imageMogrTemplate->strip();//去除元信息

快速缩略模板

提供常用图片处理模板，生成相应的缩略图。

try {
      $imageViewTemplate = new Qcloud\Cos\ImageParamTemplate\ImageViewTemplate();//创建快速缩略模板参数模版实例
      $imageViewTemplate->setMode(1);//设置缩略模式，取值范围[1，5]:1:限定缩略图的宽高最小值。该操作会将图像等比缩放直至某一边达到设定最小值，之后将另一边居中裁剪至设定值。若只指定一边，则表示宽高相等的正方形。2:限定缩略图的宽高最大值。该操作会将图像等比缩放至宽高都小于设定最大值。3:限定缩略图的宽高最小值。该操作会将图像等比缩放至宽高都大于设定最小值。4:限定缩略图的长边和短边的最小值，进行等比压缩；如果只指定一边，代表另外一边为同样的值。5:限定缩略图的长边和短边的最大值，进行等比压缩，居中裁剪；如果只指定一边，则表示宽高相等的正方形；缩放后其中一边多余的部分会被裁剪掉。
      $imageViewTemplate->setWidth(400);//设置宽度
      $imageViewTemplate->setHeight(600);//设置高度
      $imageViewTemplate->setFormat();//设置目标缩略图的图片格式，可为:jpg，bmp，gif，png，webp，缺省为原图格式
      $imageViewTemplate->setQuality(1, 85);//设置图片质量类型和图片质量，图片质量类型可为1:绝对质量，2:相对质量，3:最低质量。
      $imageViewTemplate->setQuality(1, 85, 1);//若图片质量类型为绝对质量时，可强制使用指定值。
      $result = $cosClient->getObject(array(
      'Bucket' => 'examplebucket-1250000000', //格式：BucketName-APPID
      'Key' => 'exampleobject',
      'ImageHandleParam' => $imageViewTemplate->queryString(),//生成快速缩略模板参数
  ));
  // 请求成功
  print_r($result);
} catch (\Exception $e) {
  // 请求失败
  echo($e);
}

管道操作符

CIParamTransformation 支持多操作组。

try {
  $ciParamTransformation = new Qcloud\Cos\ImageParamTemplate\CIParamTransformation();//创建管道参数模版实例
  $ciParamTransformation = new Qcloud\Cos\ImageParamTemplate\CIParamTransformation("#");//若管道操作符不为"|",需创建实例时指定
  $ciParamTransformation->addRule($imageMogrTemplate);//设置基础图片处理参数
  $ciParamTransformation->addRule($imageWatermarkTemplate);//设置图片水印处理参数
  $ciParamTransformation->addRule($textWatermarkTemplate);//设置文字水印处理参数
  $ciParamTransformation->addRule($imageViewTemplate);//设置快速缩略模板参数
$result = $cosClient->getObject(array(
      'Bucket' => 'examplebucket-1250000000', //格式：BucketName-APPID
      'Key' => 'exampleobject',
      'ImageHandleParam' => $ciParamTransformation->queryString(),//生成管道拼接参数
  ));
  // 请求成功
  print_r($result);
} catch (\Exception $e) {
  // 请求失败
  echo($e);
}