CloudInfinite sdk for ios
相关资源
- SDK源码以及demo 请参考： CloudInfinite iOS SDK
- SDK接口与参数文档请参考： 数据万象 SDK API
- 云闪图片分发介绍请参考：云闪图片分发
- TPG功能介绍：TPG
- AVIF功能介绍：AVIF
- SDK更新日志请参考：更新日志
文档概览
快速入门
为了使开发者更方便快速是使用数据万象和云闪图片分发功能，我们提供了5个SDK，开发者可根据具体需求进行选择。
| 序号 | 模块 | 功能 |
|---|---|---|
| 1 | CloudInfinite(默认模块) | 该模块包含数据万象对图片的基础操作，并支持各个操作可以相互组合，并构建URL进行网络请求； |
| 2 | Loader | 使用CIImageLoadRequest实例，请求网络图片并返回图片data数据； |
| 3 | TPG | 解码TPG格式图片并显示；即可用于显示普通图片，也可用于TPG图； |
| 4 | AVIF | 解码 AVIF 格式图片并显示，可用于显示普通图片，也可用于 AVIF 图（v1.3.8及以上）。 |
| 5 | SDWebImage-CloudInfinite | 依赖于SDWebImage、CloudInfinite模块，提供了数据万象图片基础操作功能； |
CloudInfinite 模块主要功能：
- 包含数据万象的图片基础操作，主要有：图片缩放、剪裁、旋转、格式转换、质量变换、高斯模糊、锐化、水印、获取图片主题色等；
- 将每一个操作封装为一个TransformItem，而且支持各个基础操作可以组合使用，并将组合好的操作集合构建出可以直接进行网络请求的URL;
第一步 安装 SDK CloudInfinite模块
推荐使用cocoapod方式（下面涉及集成相关模块步骤一致，不再重复） 在您工程Podfile文件中使用：
pod 'CloudInfinite'
在终端执行安装命令：
pod install
第二步 构建CIImageLoadRequest实例
- 在使用CloudInfinite 构建具有数据万象功能的图片url时，首先需要实例化 CloudInfinite类。
CloudInfinite * cloudInfinite = [CloudInfinite new];
- 实例化图片转换类 CITransformation，并设置相关操作，这里以TPG为例；更多功能见：图片转换。
CITransformation * transform = [CITransformation new];
[transform setFormatWith:CIImageTypeTPG options:CILoadTypeUrlFooter];
- 使用cloudInfinite 实例构建具有万象功能的图片url；
- 同步方式构建：
CIImageLoadRequest * imageloadRequest = [cloudInfinite requestWithBaseUrl:@"图片链接" transform:transform];
// 图片url
NSURL * imageURL = imageloadRequest.url;
// header参数
NSString * heaer = imageloadRequest.header;
- 异步方式构建
[cloudInfinite requestWithBaseUrl:@"图片链接" transform:transform request:^(CIImageLoadRequest * _Nonnull request) {
// 图片url
request.url;
// header参数
request.header;
}];
？ CIImageLoadRequest 的header参数仅在图片格式转换时 options 指定为CILoadTypeAcceptHeader时有值； 在使用自定义loader请求图片时，如果需要使用到header，则header需要拼接为：
NSDictionary * header = @{@"accept":[NSString stringWithFormat:@"image/%@",request.header]};
第三步 构建成功CIImageLoadRequest 实例后，使用CloudInfinite/Loader 模块进行图片加载；
集成 CloudInfinite/Loader模块：
pod 'CloudInfinite/Loader'
- 请求图片NSData数据 - 适用于请求TPG、AVIF图片（需集成TPG、AVIF解码模块）或者需要对图片二进制数据进行额外处理的图片；
// request 为上一步构建成功的CIImageLoadRequest实例；
[[CIImageLoader shareLoader] loadData:request loadComplete:^(NSData * _Nullable data, NSError * _Nullable error) {
// data：请求到的图片data数据；
}];
- 请求并显示图片 - 适用于请求普通图片
// 传入图片控件 imageView 以及 构建成功的CIImageLoadRequest实例；
[[CIImageLoader shareLoader]display:imageView loadRequest:request placeHolder:nil loadComplete:^(NSData * _Nullable data, NSError * _Nullable error) {
// data：请求到的图片data数据；
}];
图片转换
- 自适应加载 CIResponsiveTransformation
- 根据当前imageView控件尺寸自动调整图片大小；
- 根据系统版本自动调整最优图片格式，iOS11以下加载原格式，iOS11及以上加载heic格式；
CIResponsiveTransformation * sTransform = [[CIResponsiveTransformation alloc]initWithView:imageView
scaleType:ScaleTypeAUTOFit]
- CloudInfinite 模块中的 CITransformation类封装了万象的图片转换功能，其中包含如下功能：
一 缩放
相关链接：缩放功能接口 在使用万象图片转换功能时首先实例化 CITransformation 类，下面所有操作一致，不再重复；
CITransformation * transform = [CITransformation new];
- 图片百分比缩放
// 以缩放百分之50为例
[transform setZoomWithPercent:50 scaleType:ScalePercentTypeALL];
// scaleType 可以指定如下类型：
// 仅缩放宽度，高度不变
ScalePercentTypeOnlyWidth = 1,
// 仅缩放高度，宽度不变
ScalePercentTypeOnlyHeight,
//指定图片的宽高同时缩放
ScalePercentTypeALL,
- 指定宽高缩放
// 以宽高都指定为100 并且缩放类型为ScaleTypeAUTOFit等比缩放
[transform setZoomWithWidth:100 height:100 scaleType:ScaleTypeAUTOFit];
// 在指定宽高缩放时，scaleType可以指定的类型：
// 忽略原图宽高比例，指定图片宽度为 Width，高度为 Height ，强行缩放图片，可能导致目标图片变形
ScaleTypeAUTOFill = 1,
// 限定缩略图的宽度和高度的最大值分别为 Width 和 Height，进行等比缩放
ScaleTypeAUTOFit,
// 限定缩略图的宽度和高度的最小值分别为 Width 和 Height，进行等比缩放
ScaleTypeAUTOFITWithMin,
// 指定目标图片宽度为 Width，高度传入0， 高度等比压缩
ScaleTypeOnlyWidth,
// 指定目标图片高度为 Height，宽度传0，宽度等比压缩
ScaleTypeOnlyHeight
- 限制像素缩放-等比缩放图片，缩放后的图像，总像素数量不超过指定数量
// 缩放后的图像，总像素数量不超过1000 为例；
[transform setZoomWithArea:1000];
二 裁剪
相关链接：裁剪功能接口
- 普通裁剪
// 指定目标图片宽度、高度、相对于图片左上顶点水平向右偏移、相对于图片左上顶点水平向下偏移 进行裁剪 为例；
[transform setCutWithWidth:100 height:100 dx:30 dy:30];
- 内切圆裁剪功能，radius 是内切圆的半径，取值范围为大于0且小于原图最小边一半的整数。内切圆的圆心为图片的中心。图片格式为 gif 时，不支持该参数。
// 指定半径为100 为例
[transform setCutWithIRadius:100];
- 圆角裁剪功能，radius 为图片圆角边缘的半径，取值范围为大于0且小于原图最小边一半的整数。圆角与原图边缘相切。图片格式为 gif 时，不支持该参数。
// 指定圆角半径 100为例
[transform setCutWithRRadius:100];
- 缩放裁剪 相关链接：gravity 介绍
// 指定宽高缩放裁剪，如果为0 则不变；
[transform setCutWithCrop:100 height:100];
// 指定宽高以及gravity缩放裁剪；
[transform setCutWithCrop:100 height:100 gravity:CIGravityCenter];
- 人脸智能裁剪,基于图片中的人脸位置进行缩放裁剪。目标图片的宽度为 Width、高度为 Height。
// 裁剪人脸并宽高指定100缩放为例；
[transform setCutWithScrop:100 height:100];
三 旋转
相关链接：旋转功能接口
- 普通旋转：图片顺时针旋转角度，取值范围0 - 360 ，默认不旋转。
// 以旋转45度为例；
[transform setRotateWith:45];
- 自适应旋转：根据原图 EXIF 信息将图片自适应旋转回正。
[transform setRotateAutoOrient];
四 格式转换
相关链接：格式转换接口
- 格式转换：目标缩略图的图片格式可为：tpg、jpg、bmp、gif、png、heif、webp、yjpeg、avif 等，其中 yjpeg 为数据万象针对 jpeg 格式进行的优化，本质为 jpg 格式；缺省为原图格式。
- 使用图片格式转换，如果需要转为TPG格式，则需要依赖 'CloudInfinite/TPG' 模块；
pod 'CloudInfinite/TPG'
- 使用图片格式转换，如果需要转为AVIF格式，则需要依赖 'CloudInfinite/AVIF' 模块；
pod 'CloudInfinite/AVIF'
- 使用图片格式转换，如果需要转为WEBP格式，则需要依赖 'SDWebImageWebPCoder' 库；
pod 'SDWebImageWebPCoder'
注意 使用heic格式，需要在iOS11及以上，并且不支持gif格式图片转为heif。
// 以转为JPG为例
[transform setFormatWith:CIImageTypeJPG];
// 指定传参方式：
[transform setFormatWith:CIImageTypeTPG options:CILoadTypeUrlFooter];
CILoadTypeEnum:
// 加载类型 方式一：带 accept 头部 accept:image/ ***
CILoadTypeAcceptHeader = 0,
// 加载类型 方式二：在 url 后面中拼接 imageMogr2/format/ ***
// 如果需要方式二，则使用该值；不传默认为第一种方式
CILoadTypeUrlFooter,
注意 当指定为CILoadTypeAcceptHeader 方式传参时，并且组合了其他的转换则header失效，并且在sdk内部自动转换为footer的方式
- gif 格式优化： 只针对原图为 gif 格式，对 gif 图片格式进行的优化，降帧降颜色。 FrameNumber=1，则按照默认帧数30处理，如果图片帧数大于该帧数则截取。 FrameNumber 取值( 1,100 ]，则将图片压缩到指定帧数 （FrameNumber）。
[transform setCgif:50];
- 输出为渐进式 jpg 格式 Mode 可为0或1。0：表示不开启渐进式；1：表示开启渐进式。该参数仅在输出图片格式为 jpg 格式时有效。如果输出非 jpg 图片格式，会忽略该参数，默认值0。
[transform setInterlace:YES];
五 质量变换
相关链接：质量变换接口
// 以图片的绝对质量变换为 60为例
// type 为变换类型，下面具体介绍
[transform setQualityWithQuality:60 type:CIQualityChangeAbsolute];
注意 质量变换仅针对JPG和WEBP格式图片。
数据万象提供三种变换类型：绝对变换、相对变换、最低质量变换，其中绝对变换分为强制制定制定和不指定两种，如下：
// 图片的绝对质量，取值范围0 - 100 ，默认值为原图质量；
CIQualityChangeAbsolute = 1,
// 图片的绝对质量，取值范围0 - 100 ，强制使用指定值，例如：90!。
CIQualityChangeAbsoluteFix,
// 图片的相对质量，取值范围0 - 100 ，数值以原图质量为标准。例如原图质量为80，将 rquality 设置为80后，得到处理结果图的图片质量为64（80x80%）
CIQualityChangeRelative,
// 图片的最低质量，取值范围0 - 100 ，设置结果图的质量参数最小值。
// 例如原图质量为85，将 lquality 设置为80后，处理结果图的图片质量为85。
// 例如原图质量为60，将 lquality 设置为80后，处理结果图的图片质量会被提升至80。
CIQualityChangeLowest,
六 高斯模糊
相关链接：高斯模糊接口
- 高斯模糊功能 模糊半径，取值范围为1 - 50; 正态分布的标准差，必须大于0;
// 模糊半径20 ,正态分布的标准差20 为例
[transform setBlurRadius:20 sigma:20];
注意 图片格式为 gif 时，不支持该参数。
七 锐化
相关链接：锐化接口
- 图片锐化功能，value 为锐化参数值，取值范围为10 - 300间的整数。参数值越大，锐化效果越明显。（推荐使用70）
// 以锐化值100 为例
[transform setSharpenWith:10];
八 水印
相关链接：gravity 相关链接：图片水印接口 相关链接：文字水印接口
//imageUrl 水印图片地址
// gravity 文字水印位置，九宫格位置（参考九宫格方位图 ），默认值 SouthEast
// dx 水平（横轴）边距，单位为像素，缺省值为0
// dy 垂直（纵轴）边距，单位为像素，默认值为0
// blogo 水印图适配功能，适用于水印图尺寸过大的场景（如水印墙）。共有两种类型：
/// 当 blogo 设置为1时，水印图会被缩放至与原图相似大小后添加
/// 当 blogo 设置为2时，水印图会被直接裁剪至与原图相似大小后添加
[tran setWaterMarkWithImageUrl:@"http://tpg-1253653367.cos.ap-guangzhou.myqcloud.com/google.jpg" gravity:0 dx:0 dy:0 blogo:0];
// text 水印内容
// font 水印字体
// color 字体颜色，默认值为 #3D3D3D
// dissolve 文字透明度，取值1 - 100 ，默认90
// gravity 文字水印位置，默认值 SouthEast
// dx 水平（横轴）边距，单位为像素，缺省值为0
// dy 垂直（纵轴）边距，单位为像素，默认值为0
// batch 平铺水印功能，可将文字水印平铺至整张图片。当 batch 设置为1时，开启平铺水印功能
// degree 文字水印的旋转角度设置，取值范围为0 - 360，默认0
[transform setWaterMarkText:@"腾讯云·万象优图" font:nil textColor:nil dissolve:90 gravity:CIGravitySouth dx:100 dy:100 batch:YES degree:45];
九 获取图片主题色
相关链接：获取主题色接口
- 腾讯云数据万象通过 imageAve 接口获取图片主色调信息。
[transform setViewBackgroudColorWithImageAveColor:YES]
十 去除图片元信息
相关链接：去除图片元信息接口
- 腾讯云数据万象通过 imageMogr2 接口可去除图片元信息，包括 exif 信息。
[transform setImageStrip];
加载TPG图片
方式一 加载网络TPG图片
- 集成 CloudInfinite；
pod 'CloudInfinite'
- 在CloudInfinite模块中构建出请求TPG格式图片的链接，然后与SDWebImage配合使用加载网络TPG图片
// 实例化CloudInfinite，用来构建请求图片请求连接；
CloudInfinite * cloudInfinite = [CloudInfinite new];
// 根据用户所选万象基础功能options 进行构建CIImageLoadRequest；
CITransformation * transform = [CITransformation new];
[transform setFormatWith:CIImageTypeTPG options:CILoadTypeAcceptHeader];
// 构建图片CIImageLoadRequest
[cloudInfinite requestWithBaseUrl:@"图片链接" transform:transform request:^(CIImageLoadRequest * _Nonnull request) {
// request 构建成功的 CIImageLoadRequest 实例，
}];
方式二 使用TPG模块加载TPG图片Data数据（支持TPG动图加载，无需额外处理）
- 集成 TPG 模块；
pod 'CloudInfinite/TPG'
- 如果已经获取到TPG图片data数据，则直接使用TPG模块UIImageView+TPG类进行解码并显示；
[self.tpgImageView setTpgImageWithData:data loadComplete:^(NSData * _Nullable data，UIImage * _Nullable image, NSError * _Nullable error) {
}];
加载AVIF图片
方式一：加载网络 AVIF 图片
! CloudInfinite SDK 版本需要大于等于 v1.3.8。
- 首先集成 CloudInfinite。
pod 'CloudInfinite'
- 在 CloudInfinite 模块中构建出请求 AVIF 格式图片的链接，然后与 SDWebImage 配合使用，加载网络 AVIF 图片。
Objective-C
// 实例化 CloudInfinite，用来构建请求图片请求连接；
CloudInfinite * cloudInfinite = [CloudInfinite new];
// 根据用户所选万象基础功能 options 进行构建 CIImageLoadRequest；
CITransformation * transform = [CITransformation new];
[transform setFormatWith:CIImageTypeAVIF options:CILoadTypeUrlFooter];
// 构建图片 CIImageLoadRequest
[cloudInfinite requestWithBaseUrl:@"图片链接" transform:transform request:^(CIImageLoadRequest * _Nonnull request) {
// request 构建成功的 CIImageLoadRequest 实例，
}];
swift
// 实例化 CloudInfinite，用来构建请求图片请求连接；
let cloudInfinite = CloudInfinite();
// 根据用户所选的数据万象基础功能 options 进行构建 CIImageLoadRequest；
let transform = CITransformation();
transform.setFormatWith(CIImageFormat.typeAVIF, options: CILoadTypeEnum.urlFooter);
// 构建图片 CIImageLoadRequest
cloudInfinite.request(withBaseUrl: "图片链接", transform: transform) { (request) in
// request 构建成功的 CIImageLoadRequest 实例，
}
方式二：使用 AVIF 模块加载本地 AVIF 图片
使用 AVIF 模块加载 AVIF 图片 Data 数据，支持加载 AVIF 动图，无需额外处理。
- 首先集成 AVIF 模块。
pod 'CloudInfinite/AVIF'
- 如果已经获取到 AVIF 图片 data 数据，则直接使用 AVIF 模块 UIImageView+AVIF 类进行解码并显示。 Objective-C
[self.avifImageView setAvifImageWithData:data loadComplete:^(NSData * _Nullable data，UIImage * _Nullable image, NSError * _Nullable error) {
}];
swift
imageView.setAvifImageWith(data) { (data, image, error) in
}
与SDWebImage配合使用
- 在使用数据万象图片基础操作时需要集成 CloudInfinite/SDWebImage-CloudInfinite 模块；
pod 'CloudInfinite/SDWebImage-CloudInfinite'
- 使用（UIImageView+CI： 模仿SDWebImage调用风格，封装了一组可以传入transform的方法）
实例化CITransformation 类并添加需要使用的操作；
CITransformation * transform = [CITransformation new];
// 加入缩放功能
[transform setZoomWithPercent:50 scaleType:ScalePercentTypeOnlyWidth];
// 加入圆角功能
[transform setCutWithRRadius:100];
// 根据实际需求加入相应的功能
...
// 使用UIImageView+CI类种方法，加载图片
[self.imageView sd_CI_setImageWithURL:[NSURL URLWithString:@"图片链接"] transformation:transform];
准备工作
在使用TPG功能时 SDWebImage-CloudInfinite 需要依赖CloudInfinite/TPG 模块
pod 'CloudInfinite/TPG'
加载TPG图片
SDWebImage-CloudInfinite提供了两种加载TPG图片的方式；
方式一 调用 UIImageView+CI 加载TPG
// 构建 CITransformation实例
CITransformation * tran = [CITransformation new];
// 设置TPG格式以及传参方式
[tran setFormatWith:CIImageTypeTPG options:CILoadTypeUrlFooter];
// 调用UIImageView+CI 类种方法，加载图片
[self.imageView sd_CI_setImageWithURL:[NSURL URLWithString:@"图片链接"] transformation:transform];
方式二 全局配置加载TPG
使用场景
- 如果整个项目都需要使用TPG，或为已有项目接入TPG；
- 或者某些固定模式的图片链接需要使用TPG;
具体使用
// 在项目启动时给CIDownloaderConfig添加需要使用TPG图片的链接正则表达式；满足这个正则的图片链接都使用TPG格式加载；
// 所有图片都使用TPG加载
[[CIDownloaderConfig sharedConfig] addTPGRegularExpress:@"http(s)?:.*" paramsType:CILoadTypeUrlFooter];
// 如果有的链接不需要使用TPG，给CIDownloaderConfig 添加排除的正则；
// 请求图片主题色排除
[[CIDownloaderConfig sharedConfig] addExcloudeTPGRegularExpress:@"http(s)?:.*imageAve"];
准备工作
在使用WEBP功能时 SDWebImage-CloudInfinite 需要依赖 SDWebImageWebPCoder 库；
pod 'SDWebImageWebPCoder'
加载WEBP图片
// 实例化 CITransformation 类
CITransformation * tran = [CITransformation new];
// 设置转换为webp格式
[tran setFormatWith:CIImageTypeWEBP options:CILoadTypeUrlFooter];
// 加载图片
[self.imageView sd_CI_setImageWithURL:[NSURL URLWithString:@"图片链接"] transformation:tran];
准备工作
在使用 AVIF 功能时，SDWebImage-CloudInfinite 需要依赖 CloudInfinite/AVIF 模块。
pod 'CloudInfinite/AVIF'
调用 UIImageView+CI 加载 AVIF
Objective-C
// 构建 CITransformation实例
CITransformation * tran = [CITransformation new];
// 设置AVIF格式以及传参方式
[tran setFormatWith:CIImageTypeAVIF options:CILoadTypeUrlFooter];
// 调用UIImageView+CI 类种方法，加载图片
[self.imageView sd_CI_setImageWithURL:[NSURL URLWithString:@"图片链接"] transformation:transform];
swift
// 构建 CITransformation 实例
let transform = CITransformation();
// 设置 AVIF 格式以及传参方式
transform.setFormatWith(CIImageFormat.typeAVIF, options: CILoadTypeEnum.urlFooter);
// 调用 UIImageView+CI 类种方法，加载图片
imageView.sd_CI_setImage(with: NSURL.init(string: "图片链接"), transformation: transform)
更新日志
-
Version 1.5.1
1 新增cloudavif.a&cloudtpg.a
-
Version 1.5.0
2022-05-24 1 新增自定义网络层。 2 接入quic、HTTPDNS。 3 支持配置重试、并发数以及tpg、avif原图保护。
-
Version 1.4.4
2022-03-02 1 集成灯塔上报（TPG、AVIF）。 2 新增TPGSlim 、AVIFSlim
-
Version 1.4.1
2022-08-26
修复tpg 解码含有透明通道的图片
-
Version 1.4.0
2022-08-26
yuv增加armv7架构
-
Version 1.3.9
2022-08-26
podspec删除all_load
-
Version 1.3.8
2021-11-21
新增avif图片解码
-
Version 1.3.6
2021-05-18
修复TPG crash
-
Version 1.3.5
2020-11-05
解决本sdk与其他sdk冲突问题
-
Version 1.3.4
2020-09-21
修复部分包含透明通道gif解码白色背景问题
-
Version 1.3.3
2020-09-17
补充自定义SDWebimage解码器未实现编码方法
-
Version 1.3.2
2020-08-24
降低TPG解码内存消耗
-
Version 1.3.1
2020-08-21
优化TPG解码
-
Version 1.3.0
2020-08-19
支持WEBP图片解码渲染
-
Version 1.2.0
2020-08-18
支持TPG动图加载
支持数据万象图片基础操作
-
Version 1.0.0
2020-07-29
首次发布
图片格式转换功能
TPG图片加载功能
卸载SDK
在您工程Podfile文件中删除本sdk的依赖，然后执行
pod install
示例
完整例子请参考CIImageLoaderDemo示例工程
感谢
使用过程中如果您遇到了问题或者有更好的建议欢迎提 issue以及pull request;