iOS版

集成 Camera SDK

1. SDK 下载

SDK: iOS_SDK_v3.1.11Swift Latest

SDK 示例: iOS SDK示例代码 Latest

版本变更: Changelog New

历史版本: All Releases

2. 引入SDK文件

将 StitchingCameraSDK.xcframework 引入到项目中

3. 引入方式

在 XCode 中选择项目中的 TARGETS -> General -> Frameworks,Libraries,and Embedded Content, 点击+号, 把 StitchingCameraSDK.xcframework导入到项目中
StitchingCameraSDK.xcframework为动态编译Framework，Embeb项中选择 Embed & Sign

要了解如何与 Camera SDK 交互，请参阅以下章节。

SDK 示例说明

调用步骤请参照以下概要说明。要了解更详细的交互细节，请参考 iOS SDK示例代码

1. 初始化回调监听

swift

// StitchingCameraCallback 接口函数
// 暂存图片信息, 使用者可自行定义，此处只为示范代码
var imagesCached:[Any] = [Any](); 

/**
 * 拍照单张照片完成后的回调
 * @param imagePath 图片保存路径
 * @param imageIndex 序号，本次拍照的第几张图片
 * @param imageId 图片唯一编码 UUID
 * @param pair 与上一张拼图的区域重叠信息，用于后续拼接stitchingInfo 
*/
func takeSinglePhotoCallback(_ imagePath: String, _ imageIndex: Int, _ imageId: String, _ pair: String) {
    // 示例代码，自行根据业务场景处理
    self.imagesCached.append([imagePath, imageIndex, imageId, pair])

    // 按imageIndex升序对imagesCached进行排序
    self.imagesCached.sort { (($0 as? [Any])?[1] as? Int) ?? 0 < (($1 as? [Any])?[1] as? Int) ?? 0 }
}

/**
 * 结束拍照的任务回调
 * @param stitchingPath 拼图本地路径
 * @param stitching 拼图信息
 *        stitchingInfoVersion 0(经典拼图模式)、1(视频拼图模式)、3(丝融拼图模式)； 
 *        info 拼图信息(video stitching模式 才会有此信息)
 * */
func endTakePhotoCallback(_ stitchingPath: String, _ stitching: String) {
    // 结束拍摄时可能存在以下两种情况
    // 情况1: 此组拼图任务的单图只有一张图片,不需要向服务器发起拼图任务请求，采用单图返回的'task_id'去获取识别结果
    // 情况2: 此组拼图任务的单图有超过一张图片的情况，需要向服务器发起[拼图请求](https://retail-doc.clobotics.com/cn/open-api/api/ir-api.html#%E5%88%9B%E5%BB%BA%E6%8B%BC%E5%9B%BE%E4%BB%BB%E5%8A%A1)
    // 请参考 StitchingInfo管理

    // jsonString to Dic
    let stitchingJSONObj = toDictFromJSONString(jsonString:stitching)
    let stitchingCode:Int = stitchingJSONObj["stitchingInfoVersion"] as! Int
    if(stitchingCode == 0){
        // 请参考StitchingInfo管理中经典拼图模式的拼接
    }
    if(stitchingCode == 1) {
        // 请参考StitchingInfo管理中视频拼图模式的拼接
    }
    if(stitchingCode == 3) {
        // 请参考StitchingInfo管理中丝融拼图模式的拼接
    }
}

/**
 * 取消拍照的任务回调
 * @param imagesPath 需要清除的单图本地路径数组
 * */
func cancelTakePhotoCallback(_ imagesPath: [String]) {
    // 示例代码，自行根据业务场景处理
    
}

/**
 * 切换拍摄场景、或者放弃拍照时，触发该回调
 */
func clearAll(){
    // 示例代码，自行根据业务场景处理
    self.imagesCached = [Any]();
}

Objective-C

- (void)takeSinglePhotoCallback:(NSString *)imagePath :(NSInteger)imageIndex :(NSString *)imageId :(NSString *)pair {
    
}
- (void)endTakePhotoCallback:(NSString *)stitchingPath :(NSString *)stitching {
    
}
- (void)cancelTakePhotoCallback:(NSArray<NSString *> *)imagesPath {
   
}
- (void)clearAll {
   
}

在配置 StitchingCameraCallback 时，有个需要关注的回调:

delPhotoCallback: 用户在拍摄过程中取消拍摄时会触发该回调。处理该回调逻辑至关重要，尤其是在拼接模式下，以防止出现错误的拼接信息。

swift

/**
 * 撤销上张图片拍摄时的回调
 * @param imagePath 图片路径
 */
func delPhotoCallback(_ imagePath:String){
    // logic code to remove imapgePath from imagesCached
}

Objective-C

- (void)delPhotoCallback:(NSString *)imagePath {
   
}

2. 初始化相机配置 CameraConfig，并启用相机实例

有关 CameraConfig 的详细配置，请参阅：配置 CameraConfig。然后，使用以下代码启用相机实例。

swift

 let vc = ParentStitchController()
 // 设置监听拍照事件回调
 vc.mStitchingCallback = self 
 vc.modalPresentationStyle = .fullScreen
 // CameraConfig 的属性说明请参考配置参数说明
 vc.cameraConfig = mCameraConfig
  // 打开相机操作
 self.present(vc, animated: true)

Objective-C

ParentStitchController *vc = [[ParentStitchController alloc] init];
// 设置监听拍照事件回调
vc.mStitchingCallback = self;
vc.modalPresentationStyle = UIModalPresentationFullScreen;
// CameraConfig 的属性说明请参考配置参数说明
vc.cameraConfig = config;
// 打开相机操作
[self presentViewController:vc animated:YES completion:nil];

3. StitchingInfo 的管理

图像拼接的关键是存储图像拼接信息的 StitchingInfo。当调用 OpenAPI 中的创建拼图任务时，如果不能正确传递相关的StitchingInfo，任务可能会失败。请仔细阅读。

配置 CameraConfig

1. 拼图拍摄配置

经典拼图模式

swift

let mCameraConfig = CameraConfig()
mCameraConfig.userSelectedStitchingMode = 2;
mCameraConfig.maskStyle = 2;   //  可缺省不设置  
mCameraConfig.stitchingMinCount = 2;
mCameraConfig.stitchingMaxCount = 4;

Objective-C

CameraConfig *mCameraConfig = [[CameraConfig alloc] init];
mCameraConfig.userSelectedStitchingMode = 2;
mCameraConfig.maskStyle = 2;  //  可缺省不设置  
mCameraConfig.stitchingMinCount = 2;
mCameraConfig.stitchingMaxCount = 4;

接着调用openStitchingCamera启用相机

注意:

对于参数 stitchingMinCount 和 stitchingMaxCount，可以根据需求设置为适当的值

视频拼图模式

swift

let mCameraConfig = CameraConfig()
mCameraConfig.userSelectedStitchingMode = 1;
mCameraConfig.stitchingMinCount = 2;
mCameraConfig.stitchingMaxCount = 4;

Objective-C

CameraConfig *mCameraConfig = [[CameraConfig alloc] init];
mCameraConfig.userSelectedStitchingMode = 1;
mCameraConfig.stitchingMinCount = 2;
mCameraConfig.stitchingMaxCount = 4;

接着调用openStitchingCamera启用相机

注意:

对于参数 stitchingMinCount 和 stitchingMaxCount，可以根据需求设置为适当的值

丝融拼图模式

swift

let mCameraConfig = CameraConfig()
mCameraConfig.userSelectedStitchingMode = 3;
mCameraConfig.stitchingMinCount = 2;
mCameraConfig.maxRecordingSecs = 45;

Objective-C

CameraConfig *mCameraConfig = [[CameraConfig alloc] init];
mCameraConfig.userSelectedStitchingMode = 3;
mCameraConfig.stitchingMinCount = 2;
mCameraConfig.maxRecordingSecs = 45;

接着调用openStitchingCamera启用相机

注意:

对于参数 stitchingMinCount 和 maxRecordingSecs，可以根据需求设置为适当的值

2. 单图拍摄配置

经典单图模式

在该模式下，用户仍可以同时拍摄多张图像，而无需退出摄像机。区别于拼图模式，虽然拍摄了多张图像，但 Camera SDK 不会提供 StitchingInfo。

swift

let mCameraConfig = CameraConfig()
mCameraConfig.userSelectedStitchingMode = 2
mCameraConfig.maskStyle = 1

Objective-C

CameraConfig *mCameraConfig = [[CameraConfig alloc] init];
mCameraConfig.userSelectedStitchingMode = 2
mCameraConfig.maskStyle = 1

接着调用openStitchingCamera启用相机

注意:

对于参数 stitchingMinCount 和 stitchingMaxCount，可以根据需求设置为适当的值

纯价签模式

该模式为需要拍摄价格标签的场景引入了导向遮罩，在该模式下，用户可以同时拍摄多张图像，不同于拼图模式（包含经典拼图模式、视频拼图模式），虽然拍摄了多张图像，但 Camera SDK 不会提供 StitchingInfo，也无需管理 StitchingInfo。

swift

let mCameraConfig = CameraConfig()
/**
 * 纯价签模式，一次拍摄一张图片配置如下，其他参数启用默认值
 * */
mCameraConfig.userSelectedStitchingMode = 2
mCameraConfig.maskStyle = 3
mCameraConfig.stitchingMinCount = 1
mCameraConfig.stitchingMaxCount = 1

Objective-C

CameraConfig *mCameraConfig = [[CameraConfig alloc] init];
mCameraConfig.userSelectedStitchingMode = 2
mCameraConfig.maskStyle = 3
mCameraConfig.stitchingMinCount = 1
mCameraConfig.stitchingMaxCount = 1

接着调用openStitchingCamera启用相机

产品价签模式

该模式为需要拍摄产品和价格标签在陈列的场景引入了导向遮罩。在该模式下，用户可以同时拍摄多张图像，不同于拼图模式（包含经典拼图模式、视频拼图模式），虽然拍摄了多张图像，但 Camera SDK 不会提供 StitchingInfo，也无需管理 StitchingInfo。

swift

let mCameraConfig = CameraConfig()
/**
 * 产品价签模式，一次拍摄一张图片配置如下，其他参数启用默认值
 * */
mCameraConfig.userSelectedStitchingMode = 2
mCameraConfig.maskStyle = 4
mCameraConfig.stitchingMinCount = 1
mCameraConfig.stitchingMaxCount = 1

Objective-C

CameraConfig *mCameraConfig = [[CameraConfig alloc] init];
mCameraConfig.userSelectedStitchingMode = 2
mCameraConfig.maskStyle = 4
mCameraConfig.stitchingMinCount = 1
mCameraConfig.stitchingMaxCount = 1

接着调用openStitchingCamera启用相机

多语言支持

支持的多语言指定清单（缺省时为英文）包括：

语言	参数值
中文	`zh-Hans`
中文繁体	`zh-Hant`
英文	`en`
泰语	`th`
缅甸语	`my-MM`
法语	`fr`
葡萄牙语	`pt`
西班牙语	`es`
意大利语	`it`

CameraConfig配置language

swift

let mCameraConfig = CameraConfig()
mCameraConfig.language = "zh-Hans"

Objective-C

CameraConfig *mCameraConfig = [[CameraConfig alloc] init];
mCameraConfig.language = "zh-Hans";

CameraConfig 相关属性

功能	参数	说明	类型	默认值	版本
多语言支持	language	设置显示的语言，支持的语言	string	跟随系统	3.1.6
拍摄模式	userSelectedStitchingMode	启用时的默认拍摄模式, 1为视频拼图模式，2为经典拍摄（配合maskStyle使用可区分配置拼图拍摄、单图拍摄、价签拍摄），3为丝融拼图模式注: 配置为1时，需要SDK判断设备硬件支持视频拼图拍摄模式才生效	int	2	3.0.0
	maskStyle	启用拍摄时的遮罩引导框风格：1为单图拍摄；3为纯价签引导框；4为产品价签引导框注: 配置为1、3或4时，需要userSelectedStitchingMode = 2才生效。	int	0	3.1.5
	isFirstUse	首次启动，是否弹出拼图操作引导图	boolean	false	3.0.0
	allowRoll	允许用户沿着前后方向旋转的角度，取值范围为：0~90°	float	45	3.0.0
	allowPitch	允许用户沿着左右方向旋转的角度，取值范围为：0~90°	float	45	3.0.0
	stitchingMinCount	本次最小允许拍摄张数，0为不限制	int	0	3.0.0
	stitchingMaxCount	本次允许最大拍摄张数，0为不限制	int	0	3.0.0
	maxRecordingSecs	丝融拍摄最大时长限制(单位：秒) 注: userSelectedStitchingMode = 3时才生效。	int	0	3.1.10
	enableGEOLocator	启用拍摄时照片EXIF是否写入经纬度信息	boolean	false	3.1.4
图片质量检测	isUseLargeAngleModel	是否启用大角度模型检测注: 经典拼图模式或丝融拼图模式时（userSelectedStitchingMode = 2 && maskStyle = 2 \|\| userSelectedStitchingMode = 3）才生效	boolean	false	3.1.11
	allowLargeAngle	大角度模型允许的最大角度，取值范围：0~90° 注: isUseLargeAngleModel=true时才生效	float	20.0	3.1.10
	isUseSkuSizeModel	是否启用 SKU图片中大小占比检测注: 经典拼图模式时（userSelectedStitchingMode = 2 && maskStyle = 2）才生效	boolean	false	3.0.0
	minSkuSizeRatio	SKU大小检测最小比例，取值范围：0.0~1.0 注: isUseSkuSizeModel=true时才生效	float	0.3	3.1.10

StitchingInfo 管理

在经典拼图模式下

如SDK示例代码所示，以下逻辑必须加入到 endTakePhotoCallback(String stitchingPath, JSONObject stitchingInfo) 回调中。

swift

/**
 * in function endTakePhotoCallback definition
 * @param stitchingPath stitching local path
 * @param stitchingInfo stitching info
 * stitchingInfoVersion 0 (经典拼图模式), 1 (视频拼图模式), 3 (丝融拼图模式)
 * info puzzle information (video stitching mode will have this information)
 * BestPov latest stitching position (only class stitching mode has this information)
 * resize puzzle compression ratio (only the class stitching mode has this information) 
 * */

let info = stitchingInfo.data(using: String.Encoding.utf8)
var uploadStitchingInfo = ""
if let dict = try? JSONSerialization.jsonObject(with: info!, options: JSONSerialization.ReadingOptions.mutableContainers) as? [String : Any] {
    let stitchingData:[String: Any] = ["stitchingInfo": dict]
    uploadStitchingInfo = toJSONString(stitching: stitchingData.toJsonString() ?? "")
}

func toJSONString(stitching: Dictionary<String, Any>) -> String {
    guard let data = try? JSONSerialization.data(withJSONObject: stitching,
                                                 options: []) else {
        return ""
    }
    guard let str = String(data: data, encoding: .utf8) else {
        return ""
    }
    let encoder = JSONEncoder()
    encoder.outputFormatting = .prettyPrinted
    guard let data = try? encoder.encode(str) else{ return "" }
    guard let jsonStr = String(data: data, encoding: .utf8) else{ return "" }
    return jsonStr
}

在视频拼图模式下

以下逻辑也必须加入到 endTakePhotoCallback(String stitchingPath, JSONObject stitchingInfo) 回调中。

swift

/**
 * in function endTakePhotoCallback definition
 * @param stitchingInfo String 拼图信息
 *        stitchingInfoVersion 0(经典拼图模式) 1(视频拼图模式) 3(丝融拼图模式)； 
 *        bestPov 最佳拼接位置（classic stitching模式 才会有此信息）
 * @param stitchingPath String 拼图本地路径
 * @param stitchingInfoVersion Int 拼图信息版本 0为Classic Stitching，1为Video Stitching
 * */

// 整体StitchingInfo 是一个字符串，所以需要添加转义符号
let uploadStitchingInfo = "{\\\"stitchingInfo\\\":\(stitchingInfo)}";

在丝融拼图模式下

以下逻辑也必须加入到 endTakePhotoCallback(String stitchingPath, JSONObject stitchingInfo) 回调中。

swift

/**
 * in function endTakePhotoCallback definition
 * @param stitchingInfo String 拼图信息
 *        stitchingInfoVersion 0(经典拼图模式) 1(视频拼图模式) 3(丝融拼图模式)； 
 *        bestPov 最佳拼接位置（classic stitching模式 才会有此信息）
 * @param stitchingPath String 拼图本地路径
 * @param stitchingInfoVersion Int 拼图信息版本 0为Classic Stitching，1为Video Stitching
 * */

// 整体StitchingInfo 是一个字符串，所以需要添加转义符号
let uploadStitchingInfo = "{\\\"stitchingInfo\\\":\(stitchingInfo)}";

拼图模式下统一管理 StitchingInfo

如果你想在 endTakePhotoCallback(String stitchingPath, JSONObject stitchingInfo) 回调中共同处理 StitchingInfo，请参照以下代码

swift

func endTakePhotoCallback(_ stitchingPath: String, _ stitching: String) {
    let stitchingJSONObj = toDictFromJSONString(jsonString:stitching)
    let stitchingCode:Int = stitchingJSONObj["stitchingInfoVersion"] as! Int
    if(stitchingCode == 0){
        // 经典拼图模式
        let stitchingInfo = "{\\\"stitchingInfo\\\":\(toJSONString(stitching:stitching))}";
        print(stitchingInfo)
    }
    if(stitchingCode == 1) {
        // 视频拼图模式
        let stitchingInfo = "{\\\"stitchingInfo\\\":\(stitching)}";
        print(stitchingInfo)
    }
    if(stitchingCode == 3) {
        // 丝融拼图模式
        let stitchingInfo = "{\\\"stitchingInfo\\\":\(stitching)}";
        print(stitchingInfo)
    }
    
    // next: needed for OpenAPI: Create Stitching Picture Task param stitching_info https://retail-doc.clobotics.com/en/open-api/api/ir-api#create-stitching-picture-task

    // stitchingInfo taskIds stitchingCode
}

版本变更

如果需要查看更多历史版本，请参阅 Releases。

模块	变更项	版本号
模块	变更项	< 3.1.11	3.1.11
配置参数	isUseLargeAngleModel 变动：新增生效范围	仅在经典拼图模式userSelectedStitchingMode = 2 && maskStyle = 2配置下生效	新增支持丝融拼图模式 userSelectedStitchingMode = 3 时生效
		< 3.1.10	3.1.10
配置参数	userSelectedStitchingMode 变动：新增枚举值	可选: 1｜2	可选: 1｜2｜3 支持配置开启丝融拼图模式
	maxRecordingSecs 变动：新增	-	支持配置拍摄最大时长（秒）注: 配置时，需要userSelectedStitchingMode = 3才生效。
	allowLargeAngle 变动：新增	-	支持设置大角度模型允许的最大角度，取值范围：0~90°
	minSkuSizeRatio 变动：新增	-	支持设置SKU大小检测最小比例，取值范围：0.0~1.0
		< 3.1.9	3.1.9
兼容性	变动：支持Objective-C	-	支持Objective-C集成
		< 3.1.7	3.1.7
回调监听	cancelTakePhotoCallback 变动：新增	-	func cancelTakePhotoCallback(_ imagesPath: [String])
		< 3.1.6	3.1.6
配置参数	language 变动：新增	-	支持设置相机UI界面显示的语言
		< 3.1.5	3.1.5
配置参数	maskStyle 变动：新增枚举	可选：3	可选: 3 \| 4 启用拍摄时的遮罩引导框风格, 4为产品价签引导框注: 配置为4时，需要userSelectedStitchingMode = 2才生效。
		3.1.4	3.1.4
配置参数	enableGEOLocator 变动：新增	-	支持将拍照时的经纬度信息写入图片的EXIF信息中
		3.0.0	3.1.0
回调监听	takePhotoCallback -> takeSinglePhotoCallback 变动：函数名修改、传参	func takePhotoCallback(_ imagePath: String, _ imageIndex: Int, _ imageId: String, _ pair: String, _ stitchingVersionInfo: Int)	func takeSinglePhotoCallback(_ imagePath: String, _ imageIndex: Int, _ imageId: String, _ pair: String)
回调监听	endTakePhotoCallback 变动：传参	func endTakePhotoCallback(_ stitchingPath: String, _ stitching: String, _ stitchingVersionInfo: Int)	func endTakePhotoCallback(_ stitchingPath: String, _ stitching: String)
配置参数	maskStyle 变动：新增	-	可选：3 启用拍摄时的遮罩引导框风格, 3为纯价签引导框注: 配置为3时，需要userSelectedStitchingMode = 2才生效。

iOS版 ​

集成 Camera SDK ​

1. SDK 下载 ​

2. 引入SDK文件 ​

3. 引入方式 ​

SDK 示例说明 ​

1. 初始化回调监听 ​

2. 初始化相机配置 CameraConfig，并启用相机实例 ​

3. StitchingInfo 的管理 ​

配置 CameraConfig ​

1. 拼图拍摄配置 ​

经典拼图模式 ​

视频拼图模式 ​

丝融拼图模式 ​

2. 单图拍摄配置 ​

经典单图模式 ​

纯价签模式 ​

产品价签模式 ​

多语言支持 ​

CameraConfig 相关属性 ​

StitchingInfo 管理 ​

在经典拼图模式下 ​

在视频拼图模式下 ​

在丝融拼图模式下 ​

拼图模式下统一管理 StitchingInfo ​

版本变更 ​

如果需要查看更多历史版本，请参阅 Releases。 ​

iOS版

集成 Camera SDK

1. SDK 下载

2. 引入SDK文件

3. 引入方式

SDK 示例说明

1. 初始化回调监听

2. 初始化相机配置 CameraConfig，并启用相机实例

3. StitchingInfo 的管理

配置 CameraConfig

1. 拼图拍摄配置

经典拼图模式

视频拼图模式

丝融拼图模式

2. 单图拍摄配置

经典单图模式

纯价签模式

产品价签模式

多语言支持

CameraConfig 相关属性

StitchingInfo 管理

在经典拼图模式下

在视频拼图模式下

在丝融拼图模式下

拼图模式下统一管理 StitchingInfo

版本变更

如果需要查看更多历史版本，请参阅 Releases。