尧图网站建设 
简介面向 iOS 开发者的文档扫描与矩形边缘识别示例工程核心解决 OCR 前文档边缘定位问题。工程基于原生 CoreImage 框架中的 CIDetectorTypeRectangle 检测器实现矩形区域检测从图像输入到边缘坐标输出都有清晰实现并附原理讲解文章帮助读者理解底层逻辑。压缩包共 411 个文件、约 484KB包含 56 个 h 头文件、24 个 m 实现文件、18 个 PNG 图片资源、13 个 sample 示例文件、12 个 JSON 数据文件以及 plist、storyboard、pch、pbxproj 等完整的 Xcode 工程配置目录结构清晰便于直接打开运行、断点调试或二次开发。目前已有 1286 人学习下载适合具备一定 iOS 基础、希望掌握原生视觉框架的开发者。阅读源码可学会 CIDetector 的调用方式、矩形特征参数调优方法也可参考界面布局与交互设计将检测结果接入自定义取景框或后续 OCR 流程是一份聚焦清晰、可直接落地的 iOS 视觉开发参考。1. 矩形边缘识别先行iOS Document Scanner 里 CIDetectorTypeRectangle 的角色CIDetectorTypeRectangle 是 Core Image 里专门做矩形边缘识别的检测器类型文档扫描类 App 的第一道工序就是它。对着一沓纸质文档打开相机屏幕里瞬间出现一个高亮框把 A4 纸的四个角压在框内——这背后不是 OCR而是边缘检测算法在逐帧找四边形。它的优势是零训练门槛不需要模型文件初始化一次就能从 CIImage 返回矩形四角坐标iOS 8 到 iOS 17 全系可用适合文档对齐、票据裁边、透视图预处理。下面按检测、矫正、选帧的顺序展开把 CIDetectorTypeRectangle 的参数边界、坐标映射、透视矫正和连拍选帧讲透最后给出排错与验证技巧。2. CIDetectorTypeRectangle 的检测原理与参数边界2.1 CIDetector 在 Core Image 里的定位从边缘检测到四边形拟合CIDetector 是 Core Image 里检测能力的统一入口TypeRectangle 负责从图像里找矩形或四边形区域。它内部的流程大致分两步先做边缘检测找出和背景有灰度跳变的像素位置再把它们连接成候选边缘最后筛选出能组成四边形的组合。这一步和课本里的 Prewitt 边缘检测原理同源只是 Core Image 把边缘连接和四边形拟合封装成了黑盒你不需要自己写卷积算子。因此它的表现高度依赖输入图的条件边缘越清晰、背景越干净召回率越高一旦阴影切断文档边缘或者背景里地板砖、书脊这类平行线过多角点就会飘。这个原理直接决定了用法喂给 CIDetectorTypeRectangle 的图像要尽量接近真实拍摄帧而不是经过二次编码保存的小图。我一般会直接用相机回调里 CMSampleBuffer 转出来的 CIImage或从相册读取时用 CGImageSource 拿原始 CGImage避免 UIImage 对方向做隐式转换后丢掉检测需要的细节。2.2 初始化参数表Accuracy、AspectRatio、MinFeatureSize 怎么配合CIDetectorTypeRectangle 能配置的选项不多但每个都对边界情况起作用。先看初始化代码let ciContext CIContext(options: [.useSoftwareRenderer: false]) // 复用 GPU 上下文 let options: [String: Any] [ CIDetectorAccuracy: CIDetectorAccuracyHigh, CIDetectorAspectRatio: 0.7, // A4 短边/长边约 0.707 CIDetectorMinFeatureSize: 0.15 // 最小矩形边长占图像短边的比例 ] let detector CIDetector(ofType: CIDetectorTypeRectangle, context: ciContext, options: options)这段代码有两个容易忽略的点。CIContext 要放进 App 生命周期里复用每次新建会重新分配 GPU 资源视频流扫描时会造成可感知的延迟CIDetector 本身不是线程安全的不同线程要各自创建 detector同一个 detector 在多个队列上并发调用 features(in:) 会产生数据竞争。选项取值范围语义对文档扫描的影响CIDetectorAccuracyLow / High精度档位Low 速度快角点噪声大High 角点更准耗时上浮CIDetectorAspectRatio0.0 ~ 1.0矩形短边与长边的最小比值0.7 接近 A4 纸比例可过滤细长误检CIDetectorMinFeatureSize0.0 ~ 1.0最小矩形边长占图像短边的比例0.15 过滤小卡片过大会漏掉远处的文档AspectRatio 是这里最容易用错的一个。它的含义不是目标的精确宽高比而是短边与长边的下限A4 纸 210:297 换算约 0.707所以扫描文档传 0.7 能把细长形误检挡掉。但如果目标是身份证、名片或任意比例票据我一般不建议传这个键靠后级的面积排序过滤比在参数上反复试 0.6、0.8 更省事。MinFeatureSize 要和拍摄距离联动用户习惯站远拍整张桌面时0.05 才不会漏检取景框里文档占比超过三分之一时0.15 是安全的。2.3 和 Vision VNDetectRectanglesRequest 的选型边界iOS 11 之后Vision 的 VNDetectRectanglesRequest 提供了同类能力返回结果也是四角点A12 芯片上视频流里更快。如果项目最低版本是 iOS 11很多团队会直接选 Vision但 CIDetectorTypeRectangle 在两个场景下仍然占优要兼容 iOS 8~10 的老设备或者你已经用 Core Image 做后面的 CIPerspectiveCorrection整个管线都跑在 CIContext 上少一次跨框架资源拷贝。选型的关键不是谁更先进而是谁离你的现有管线更近。单张拍照两者差别不大连续帧才需要把 Vision 作为优先项。VNDetectRectanglesRequest 返回的是归一化四角点坐标原点和 CIDetector 一致只要把检测入口封成一层接口后面的透视矫正和选帧逻辑可以共用。3. 用 CIDetectorTypeRectangle 写出文档扫描的最小可跑工程3.1 图像入口CIImage 的两种来源最小工程的输入最好是直接拿 CIImage。相机回调里的转换一行代码guard let pixelBuffer CMSampleBufferGetImageBuffer(sampleBuffer) else { return } let cameraImage CIImage(cvPixelBuffer: pixelBuffer) // 零拷贝包装不复制像素从相册选图时优先走 CGImageSourceguard let source CGImageSourceCreateWithURL(url as CFURL, nil) else { return } let cgImage CGImageSourceCreateImageAtIndex(source, 0, nil)! let ciImage CIImage(cgImage: cgImage)第一段的 CIImage(cvPixelBuffer:) 不复制像素内存开销很小第二段走 CGImageSource 是为了保留 EXIF 方向信息方向留在 CIImage 里后面往 features(in:options:) 传 CIDetectorImageOrientation 时不需要反向推断。UIImage 的问题在于它会把方向隐式统一成向上你拿到的四角坐标和屏幕显示角度对不上排查成本高。3.2 调用 features(in:) 并按面积选主矩形CIDetector 的调用面很窄核心就是 features(in:)func detectRectangle(in image: CIImage) - CIRectangleFeature? { guard let features detector.features(in: image) as? [CIRectangleFeature], !features.isEmpty else { return nil } return features .filter { rect in let area rect.bounds.width * rect.bounds.height return area 5000 // 按自己的分辨率调这个下限 } .max { lhs, rhs in let lhsArea lhs.bounds.width * lhs.bounds.height let rhsArea rhs.bounds.width * rhs.bounds.height return lhsArea rhsArea // 面积最大的候选优先 } }这块逻辑分三层。features(in:) 返回的数组没有顺序保证同一帧里可能出现文档和窗框多个矩形所以必须按面积排序filter 里的 5000 是像素面积阈值1080p 下文档占比过小时要下调max 取这一帧里面积最大的候选作为主矩形。CIRectangleFeature 的 bounds 是轴对齐外框而不是四边形本身排序时用它做近似是好用的。3.3 四角点坐标从图像空间映射到视图空间这是新手最容易翻车的一步。CIDetectorTypeRectangle 返回的 topLeft、topRight、bottomLeft、bottomRight 是图像像素坐标原点在左下角、Y 轴向上UIView 的坐标原点在左上角、Y 轴向下。直接画框框会整体上下颠倒。转换公式是一个 Y 轴翻转加一个等比缩放let imageHeight image.extent.height let viewPoints: [CGPoint] [ CGPoint(x: feature.topLeft.x, y: imageHeight - feature.topLeft.y), CGPoint(x: feature.topRight.x, y: imageHeight - feature.topRight.y), CGPoint(x: feature.bottomRight.x, y: imageHeight - feature.bottomRight.y), CGPoint(x: feature.bottomLeft.x, y: imageHeight - feature.bottomLeft.y) ]如果在 UIImageView 上用 scaleAspectFit 显示还要把上面结果乘上缩放系数scaleX 视图宽度 / 图像宽度scaleY 视图高度 / 图像高度。最常见的错误是只做 Y 翻转忘了缩放或者只乘一个系数。坐标空间的关系见下表坐标空间原点位置Y 轴方向单位CIImage / CIRectangleFeature左下角向上像素UIView 显示层左上角向下点注意CIRectangleFeature 的四个角顺序在个别 iOS 版本里出现过交换绘制前先做一次凸包排序避免框画成交叉线。4. 从矩形边缘检测到文档成片透视矫正与连拍选帧4.1 CIPerspectiveCorrection 的输入顺序校验矩形边缘检测的最终价值是拿到一张正面视角的文档图。拿到四角点后用 CIPerspectiveCorrection 做透视矫正func perspectiveCorrected(from image: CIImage, feature: CIRectangleFeature) - CIImage? { let filter CIFilter(name: CIPerspectiveCorrection) filter?.setValue(image, forKey: kCIInputImageKey) filter?.setValue(CIVector(cgPoint: feature.topLeft), forKey: inputTopLeft) // 注意均为左下角原点系 filter?.setValue(CIVector(cgPoint: feature.topRight), forKey: inputTopRight) filter?.setValue(CIVector(cgPoint: feature.bottomLeft), forKey: inputBottomLeft) filter?.setValue(CIVector(cgPoint: feature.bottomRight), forKey: inputBottomRight) return filter?.outputImage }这里要给四个角做一次几何校验凸包内角都小于 180 度且 topLeft 到 topRight 的距离与 bottomLeft 到 bottomRight 的距离比值在 0.81.2 之间。如果矫正出来的图上下颠倒问题不在滤镜参数而是这四个角没有按真实文档的顺序传入。CIPerspectiveCorrection 的坐标沿用 CIImage 像素坐标系这里的角点直接传检测结果就行不需要做视图坐标翻转。4.2 连拍选帧用滑动平均判断文档是否就位录像模式下要解决什么时候自动按快门。单帧检测不可靠手抖、对焦没跟上、手指挡住文档边缘的瞬间角点会剧烈跳动。常见做法是维护最近 5 帧的角点数组算当前帧和均值之间的平均偏移// 四个角的平均偏移单位点 // currentPoints 与 movingAverage 都是 [topLeft, topRight, bottomRight, bottomLeft] let offset zip(currentPoints, movingAverage).reduce(0.0) { acc, pair in acc hypot(pair.0.x - pair.1.x, pair.0.y - pair.1.y) } / 4.0当 offset 低于阈值且当前帧矩形面积大于前一帧就触发一次拍照。阈值按预览分辨率定下面是一组参考值不同机型按实际画布尺寸缩放预览分辨率平均偏移阈值检测采样率720p12pt 以内15 fps1080p20pt 以内10 fps同时要把检测帧采样率压到 10~15 fps不要每帧全分辨率跑。在 A13 芯片上1080p 的 CIDetectorTypeRectangle 高精度单次调用大约几十毫秒每帧跑会直接拖低相机帧率。4.3 预处理顺序先亮度后锐化最后再进检测器对 CIDetectorTypeRectangle 真正有正面影响的预处理不多优先级从高到低先做亮度均衡再做轻微锐化最后送检测。过暗帧可以先做一次 CIGammaAdjust参数 1.21.5过曝帧重点用 CIColorControls 把对比度拉到 1.1。不要为了检测把图改出明显画质损伤因为同一张图检测完还要送去矫正和输出。另一个常见误检来自阴影文档投影刚好落在纸张边缘外几毫米会让检测器把阴影外框也识别成矩形这时可以用角点位置上的梯度值做二次确认或者在 UI 上提示用户避开强侧光。5. CIDetectorTypeRectangle 的坑与验证技巧5.1 orientation相册竖拍图检测不到的首因从相册读竖拍图时经常一张都检不出来问题在方向。UIImage 转 CIImage 不会把 UIImageOrientation 带给检测器正确做法是 3.1 那样用 CGImageSource 读原始图把 EXIF 方向的 orientation 值传给 features(in:options:)。CIDetectorImageOrientation 的取值是 1~8不要直接拿 UIInterfaceOrientation 的数字去套两边编码不一样。5.2 先用单元测试锁回归再上真机模拟器没有摄像头但检测逻辑可以离线测。准备两三张带明显卡片的测试图把检测函数做成独立接口写一个单元测试func testDetectRectangleOnSampleImage() throws { let url try XCTUnwrap(Bundle.main.url(forResource: sample_card, withExtension: jpg)) let source CGImageSourceCreateWithURL(url as CFURL, nil)! let cgImage CGImageSourceCreateImageAtIndex(source, 0, nil)! let image CIImage(cgImage: cgImage) let detector CIDetector(ofType: CIDetectorTypeRectangle, context: CIContext(), options: [CIDetectorAccuracy: CIDetectorAccuracyHigh]) let feature detector.features(in: image).first XCTAssertNotNil(feature) // 卡片图至少要能检出主矩形 }这套用例在模拟器上先跑通再连真机调视频流。iOS 16 之后真机调试还需要先在设置里打开 iOS 开发者模式否则 Xcode 装不上 App这个和算法无关但最容易卡住新人。5.3 召回率不够时的最后手段漏检反复出现时把 CIDetectorAspectRatio 选项去掉不做长宽比假设用后级的面积排序和角点校验去过滤比在 0.6、0.7、0.8 之间反复试参数更值得。你可以把 aspectRatio 从选项里删掉只把面积和角点校验留在业务层再跑一遍 5.2 的单元测试召回率变化一眼就能看出来。本文还有配套的精品资源点击获取 iOS文档扫描核心：CIDetectorTypeRectangle矩形检测与透视矫正
简介面向 iOS 开发者的文档扫描与矩形边缘识别示例工程核心解决 OCR 前文档边缘定位问题。工程基于原生 CoreImage 框架中的 CIDetectorTypeRectangle 检测器实现矩形区域检测从图像输入到边缘坐标输出都有清晰实现并附原理讲解文章帮助读者理解底层逻辑。压缩包共 411 个文件、约 484KB包含 56 个 h 头文件、24 个 m 实现文件、18 个 PNG 图片资源、13 个 sample 示例文件、12 个 JSON 数据文件以及 plist、storyboard、pch、pbxproj 等完整的 Xcode 工程配置目录结构清晰便于直接打开运行、断点调试或二次开发。目前已有 1286 人学习下载适合具备一定 iOS 基础、希望掌握原生视觉框架的开发者。阅读源码可学会 CIDetector 的调用方式、矩形特征参数调优方法也可参考界面布局与交互设计将检测结果接入自定义取景框或后续 OCR 流程是一份聚焦清晰、可直接落地的 iOS 视觉开发参考。1. 矩形边缘识别先行iOS Document Scanner 里 CIDetectorTypeRectangle 的角色CIDetectorTypeRectangle 是 Core Image 里专门做矩形边缘识别的检测器类型文档扫描类 App 的第一道工序就是它。对着一沓纸质文档打开相机屏幕里瞬间出现一个高亮框把 A4 纸的四个角压在框内——这背后不是 OCR而是边缘检测算法在逐帧找四边形。它的优势是零训练门槛不需要模型文件初始化一次就能从 CIImage 返回矩形四角坐标iOS 8 到 iOS 17 全系可用适合文档对齐、票据裁边、透视图预处理。下面按检测、矫正、选帧的顺序展开把 CIDetectorTypeRectangle 的参数边界、坐标映射、透视矫正和连拍选帧讲透最后给出排错与验证技巧。2. CIDetectorTypeRectangle 的检测原理与参数边界2.1 CIDetector 在 Core Image 里的定位从边缘检测到四边形拟合CIDetector 是 Core Image 里检测能力的统一入口TypeRectangle 负责从图像里找矩形或四边形区域。它内部的流程大致分两步先做边缘检测找出和背景有灰度跳变的像素位置再把它们连接成候选边缘最后筛选出能组成四边形的组合。这一步和课本里的 Prewitt 边缘检测原理同源只是 Core Image 把边缘连接和四边形拟合封装成了黑盒你不需要自己写卷积算子。因此它的表现高度依赖输入图的条件边缘越清晰、背景越干净召回率越高一旦阴影切断文档边缘或者背景里地板砖、书脊这类平行线过多角点就会飘。这个原理直接决定了用法喂给 CIDetectorTypeRectangle 的图像要尽量接近真实拍摄帧而不是经过二次编码保存的小图。我一般会直接用相机回调里 CMSampleBuffer 转出来的 CIImage或从相册读取时用 CGImageSource 拿原始 CGImage避免 UIImage 对方向做隐式转换后丢掉检测需要的细节。2.2 初始化参数表Accuracy、AspectRatio、MinFeatureSize 怎么配合CIDetectorTypeRectangle 能配置的选项不多但每个都对边界情况起作用。先看初始化代码let ciContext CIContext(options: [.useSoftwareRenderer: false]) // 复用 GPU 上下文 let options: [String: Any] [ CIDetectorAccuracy: CIDetectorAccuracyHigh, CIDetectorAspectRatio: 0.7, // A4 短边/长边约 0.707 CIDetectorMinFeatureSize: 0.15 // 最小矩形边长占图像短边的比例 ] let detector CIDetector(ofType: CIDetectorTypeRectangle, context: ciContext, options: options)这段代码有两个容易忽略的点。CIContext 要放进 App 生命周期里复用每次新建会重新分配 GPU 资源视频流扫描时会造成可感知的延迟CIDetector 本身不是线程安全的不同线程要各自创建 detector同一个 detector 在多个队列上并发调用 features(in:) 会产生数据竞争。选项取值范围语义对文档扫描的影响CIDetectorAccuracyLow / High精度档位Low 速度快角点噪声大High 角点更准耗时上浮CIDetectorAspectRatio0.0 ~ 1.0矩形短边与长边的最小比值0.7 接近 A4 纸比例可过滤细长误检CIDetectorMinFeatureSize0.0 ~ 1.0最小矩形边长占图像短边的比例0.15 过滤小卡片过大会漏掉远处的文档AspectRatio 是这里最容易用错的一个。它的含义不是目标的精确宽高比而是短边与长边的下限A4 纸 210:297 换算约 0.707所以扫描文档传 0.7 能把细长形误检挡掉。但如果目标是身份证、名片或任意比例票据我一般不建议传这个键靠后级的面积排序过滤比在参数上反复试 0.6、0.8 更省事。MinFeatureSize 要和拍摄距离联动用户习惯站远拍整张桌面时0.05 才不会漏检取景框里文档占比超过三分之一时0.15 是安全的。2.3 和 Vision VNDetectRectanglesRequest 的选型边界iOS 11 之后Vision 的 VNDetectRectanglesRequest 提供了同类能力返回结果也是四角点A12 芯片上视频流里更快。如果项目最低版本是 iOS 11很多团队会直接选 Vision但 CIDetectorTypeRectangle 在两个场景下仍然占优要兼容 iOS 8~10 的老设备或者你已经用 Core Image 做后面的 CIPerspectiveCorrection整个管线都跑在 CIContext 上少一次跨框架资源拷贝。选型的关键不是谁更先进而是谁离你的现有管线更近。单张拍照两者差别不大连续帧才需要把 Vision 作为优先项。VNDetectRectanglesRequest 返回的是归一化四角点坐标原点和 CIDetector 一致只要把检测入口封成一层接口后面的透视矫正和选帧逻辑可以共用。3. 用 CIDetectorTypeRectangle 写出文档扫描的最小可跑工程3.1 图像入口CIImage 的两种来源最小工程的输入最好是直接拿 CIImage。相机回调里的转换一行代码guard let pixelBuffer CMSampleBufferGetImageBuffer(sampleBuffer) else { return } let cameraImage CIImage(cvPixelBuffer: pixelBuffer) // 零拷贝包装不复制像素从相册选图时优先走 CGImageSourceguard let source CGImageSourceCreateWithURL(url as CFURL, nil) else { return } let cgImage CGImageSourceCreateImageAtIndex(source, 0, nil)! let ciImage CIImage(cgImage: cgImage)第一段的 CIImage(cvPixelBuffer:) 不复制像素内存开销很小第二段走 CGImageSource 是为了保留 EXIF 方向信息方向留在 CIImage 里后面往 features(in:options:) 传 CIDetectorImageOrientation 时不需要反向推断。UIImage 的问题在于它会把方向隐式统一成向上你拿到的四角坐标和屏幕显示角度对不上排查成本高。3.2 调用 features(in:) 并按面积选主矩形CIDetector 的调用面很窄核心就是 features(in:)func detectRectangle(in image: CIImage) - CIRectangleFeature? { guard let features detector.features(in: image) as? [CIRectangleFeature], !features.isEmpty else { return nil } return features .filter { rect in let area rect.bounds.width * rect.bounds.height return area 5000 // 按自己的分辨率调这个下限 } .max { lhs, rhs in let lhsArea lhs.bounds.width * lhs.bounds.height let rhsArea rhs.bounds.width * rhs.bounds.height return lhsArea rhsArea // 面积最大的候选优先 } }这块逻辑分三层。features(in:) 返回的数组没有顺序保证同一帧里可能出现文档和窗框多个矩形所以必须按面积排序filter 里的 5000 是像素面积阈值1080p 下文档占比过小时要下调max 取这一帧里面积最大的候选作为主矩形。CIRectangleFeature 的 bounds 是轴对齐外框而不是四边形本身排序时用它做近似是好用的。3.3 四角点坐标从图像空间映射到视图空间这是新手最容易翻车的一步。CIDetectorTypeRectangle 返回的 topLeft、topRight、bottomLeft、bottomRight 是图像像素坐标原点在左下角、Y 轴向上UIView 的坐标原点在左上角、Y 轴向下。直接画框框会整体上下颠倒。转换公式是一个 Y 轴翻转加一个等比缩放let imageHeight image.extent.height let viewPoints: [CGPoint] [ CGPoint(x: feature.topLeft.x, y: imageHeight - feature.topLeft.y), CGPoint(x: feature.topRight.x, y: imageHeight - feature.topRight.y), CGPoint(x: feature.bottomRight.x, y: imageHeight - feature.bottomRight.y), CGPoint(x: feature.bottomLeft.x, y: imageHeight - feature.bottomLeft.y) ]如果在 UIImageView 上用 scaleAspectFit 显示还要把上面结果乘上缩放系数scaleX 视图宽度 / 图像宽度scaleY 视图高度 / 图像高度。最常见的错误是只做 Y 翻转忘了缩放或者只乘一个系数。坐标空间的关系见下表坐标空间原点位置Y 轴方向单位CIImage / CIRectangleFeature左下角向上像素UIView 显示层左上角向下点注意CIRectangleFeature 的四个角顺序在个别 iOS 版本里出现过交换绘制前先做一次凸包排序避免框画成交叉线。4. 从矩形边缘检测到文档成片透视矫正与连拍选帧4.1 CIPerspectiveCorrection 的输入顺序校验矩形边缘检测的最终价值是拿到一张正面视角的文档图。拿到四角点后用 CIPerspectiveCorrection 做透视矫正func perspectiveCorrected(from image: CIImage, feature: CIRectangleFeature) - CIImage? { let filter CIFilter(name: CIPerspectiveCorrection) filter?.setValue(image, forKey: kCIInputImageKey) filter?.setValue(CIVector(cgPoint: feature.topLeft), forKey: inputTopLeft) // 注意均为左下角原点系 filter?.setValue(CIVector(cgPoint: feature.topRight), forKey: inputTopRight) filter?.setValue(CIVector(cgPoint: feature.bottomLeft), forKey: inputBottomLeft) filter?.setValue(CIVector(cgPoint: feature.bottomRight), forKey: inputBottomRight) return filter?.outputImage }这里要给四个角做一次几何校验凸包内角都小于 180 度且 topLeft 到 topRight 的距离与 bottomLeft 到 bottomRight 的距离比值在 0.81.2 之间。如果矫正出来的图上下颠倒问题不在滤镜参数而是这四个角没有按真实文档的顺序传入。CIPerspectiveCorrection 的坐标沿用 CIImage 像素坐标系这里的角点直接传检测结果就行不需要做视图坐标翻转。4.2 连拍选帧用滑动平均判断文档是否就位录像模式下要解决什么时候自动按快门。单帧检测不可靠手抖、对焦没跟上、手指挡住文档边缘的瞬间角点会剧烈跳动。常见做法是维护最近 5 帧的角点数组算当前帧和均值之间的平均偏移// 四个角的平均偏移单位点 // currentPoints 与 movingAverage 都是 [topLeft, topRight, bottomRight, bottomLeft] let offset zip(currentPoints, movingAverage).reduce(0.0) { acc, pair in acc hypot(pair.0.x - pair.1.x, pair.0.y - pair.1.y) } / 4.0当 offset 低于阈值且当前帧矩形面积大于前一帧就触发一次拍照。阈值按预览分辨率定下面是一组参考值不同机型按实际画布尺寸缩放预览分辨率平均偏移阈值检测采样率720p12pt 以内15 fps1080p20pt 以内10 fps同时要把检测帧采样率压到 10~15 fps不要每帧全分辨率跑。在 A13 芯片上1080p 的 CIDetectorTypeRectangle 高精度单次调用大约几十毫秒每帧跑会直接拖低相机帧率。4.3 预处理顺序先亮度后锐化最后再进检测器对 CIDetectorTypeRectangle 真正有正面影响的预处理不多优先级从高到低先做亮度均衡再做轻微锐化最后送检测。过暗帧可以先做一次 CIGammaAdjust参数 1.21.5过曝帧重点用 CIColorControls 把对比度拉到 1.1。不要为了检测把图改出明显画质损伤因为同一张图检测完还要送去矫正和输出。另一个常见误检来自阴影文档投影刚好落在纸张边缘外几毫米会让检测器把阴影外框也识别成矩形这时可以用角点位置上的梯度值做二次确认或者在 UI 上提示用户避开强侧光。5. CIDetectorTypeRectangle 的坑与验证技巧5.1 orientation相册竖拍图检测不到的首因从相册读竖拍图时经常一张都检不出来问题在方向。UIImage 转 CIImage 不会把 UIImageOrientation 带给检测器正确做法是 3.1 那样用 CGImageSource 读原始图把 EXIF 方向的 orientation 值传给 features(in:options:)。CIDetectorImageOrientation 的取值是 1~8不要直接拿 UIInterfaceOrientation 的数字去套两边编码不一样。5.2 先用单元测试锁回归再上真机模拟器没有摄像头但检测逻辑可以离线测。准备两三张带明显卡片的测试图把检测函数做成独立接口写一个单元测试func testDetectRectangleOnSampleImage() throws { let url try XCTUnwrap(Bundle.main.url(forResource: sample_card, withExtension: jpg)) let source CGImageSourceCreateWithURL(url as CFURL, nil)! let cgImage CGImageSourceCreateImageAtIndex(source, 0, nil)! let image CIImage(cgImage: cgImage) let detector CIDetector(ofType: CIDetectorTypeRectangle, context: CIContext(), options: [CIDetectorAccuracy: CIDetectorAccuracyHigh]) let feature detector.features(in: image).first XCTAssertNotNil(feature) // 卡片图至少要能检出主矩形 }这套用例在模拟器上先跑通再连真机调视频流。iOS 16 之后真机调试还需要先在设置里打开 iOS 开发者模式否则 Xcode 装不上 App这个和算法无关但最容易卡住新人。5.3 召回率不够时的最后手段漏检反复出现时把 CIDetectorAspectRatio 选项去掉不做长宽比假设用后级的面积排序和角点校验去过滤比在 0.6、0.7、0.8 之间反复试参数更值得。你可以把 aspectRatio 从选项里删掉只把面积和角点校验留在业务层再跑一遍 5.2 的单元测试召回率变化一眼就能看出来。本文还有配套的精品资源点击获取