OC之AVCapturePhotoSettings

AVCapturePhotoSettings 用于拍摄单个照片的一些相关设置，继承自NSObject。

照片设置关系图.png

AVCapturePhotoSettings实例可以包含任何设置组合，无论该组合对于给定的AVCaptureSession是否有效。
要拍摄照片，需要配置AVCapturePhotoSettings对象，并传递给AVCapturePhotoOutput的实例方法- capturePhotoWithSettings:delegate: ；AVCapturePhotoOutput会验证设置AVCapturePhotoSettings是否有效；如果该设置 和 协议方法不符合要求，则会引发异常。例如，flashMode设置必须指定AVCapturePhotoOutput的supportedFlashModes数组中存在的值。

1、创建AVCapturePhotoSettings

RAW 文件是相机的原始数据，占据内存很大，可以对图片进行无损的修改，该文件文件必须用专用软件方能打开；可以说有了RAW格式，图片质量可以上一个档次。JPEG 是静态图像压缩标准，.jpeg 是一种有损压缩格式，能够将图像压缩在很小的储存空间，图像中重复或不重要的资料会被丢失，因此容易造成图像数据的损伤。

1.1、默认设置

+ (instancetype)photoSettings;

创建一个默认对象；该默认对象以 JPEG 格式提供单张图像。

1.2、指定的输出格式：如 JPEG 格式

+ (instancetype)photoSettingsWithFormat:(NSDictionary<NSString *,id> *)format;

创建一个指定的输出格式的对象，如是否压缩照片：

• 参数 format ：核心视频像素缓冲区属性或AVFoundation视频设置常量字典。

要以未压缩格式拍摄照片，例如420f，420v或BGRA，在format中设置密钥kCVPixelBufferPixelFormatTypeKey。相应的值必须是AVCapturePhotoOutput的availablePhotoPixelFormatTypes数组中列出的像素格式标识符之一。

要以压缩格式（如JPEG）拍摄照片，在format中设置密钥AVVideoCodecKey。相应的值必须是AVCapturePhotoOutput的availablePhotoCodecTypes数组中列出的编解码器标识符之一。 对于压缩格式，还可以使用密钥AVVideoQualityKey指定压缩级别。

1.3、仅拍摄RAW格式

+ (instancetype)photoSettingsWithRawPixelFormatType:(OSType)rawPixelFormatType;

创建一个RAW格式的对象：

• 参数 rawPixelFormatType ：用于拍摄的 RAW 像素格式类型。此值必须是AVCapturePhotoOutput的availableRawPhotoPixelFormatTypes数组中列出的格式标识符之一。

1.4、指定RAW格式 与 处理格式

+ (instancetype)photoSettingsWithRawPixelFormatType:(OSType)rawPixelFormatType
processedFormat:(NSDictionary<NSString *,id> *)processedFormat;

创建一个以RAW格式和处理格式（如JPEG）拍摄照片的对象：

• 参数 rawPixelFormatType ：用于拍摄的 RAW 像素格式类型。此值必须是AVCapturePhotoOutput的availableRawPhotoPixelFormatTypes数组中列出的格式标识符之一。
• 参数 processedFormat ：核心视频像素缓冲区属性或AVFoundation视频设置常量字典。

1.5、指定的输出文件类型

+ (instancetype)photoSettingsWithRawPixelFormatType:(OSType)rawPixelFormatType
rawFileType:(AVFileType)rawFileType
processedFormat:(NSDictionary<NSString *,id> *)processedFormat
processedFileType:(AVFileType)processedFileType;

使用指定的输出文件类型创建一个以RAW格式和处理格式（如JPEG）拍摄照片的对象：

• 参数 rawFileType ：最终输出RAW图像的文件格式。如果没有首选文件格式，则传递nil，AVCapturePhotoOutput将自动选择适合rawPixelFormatType参数的默认文件格式。
• 参数 processedFileType ：最终输出已处理图像的文件格式。如果没有首选文件格式，则传递nil，AVCapturePhotoOutput将自动选择适合processedFormat参数的默认文件格式。

1.6、重复使用照片设置

每个AVCapturePhotoSettings实例只能被一次拍摄使用，否则uniqueID会与之前的拍摄设置的uniqueID相同，导致-capturePhotoWithSettings:delegate:方法异常 NSInvalidArgumentException 。

我们可以使用下述方法创建一个新的AVCapturePhotoSettings，来实现重复使用特定的设置组合的需求。新创建的实例的uniqueID属性具有新的唯一值，但会复制photoSettings参数中所有其他属性的值。

+ (instancetype)photoSettingsFromPhotoSettings:(AVCapturePhotoSettings *)photoSettings;

2、AVCapturePhotoSettings 的唯一标识

@property(readonly) int64_t uniqueID;

创建AVCapturePhotoSettings 实例会自动为此属性分配唯一值。

使用此属性可跟踪照片拍摄请求。在AVCapturePhotoOutput的协议方法都包含一个AVCaptureResolvedPhotoSettings实例，其uniqueID属性与用于请求拍摄时创建的AVCapturePhotoSettings实例的uniqueID值相匹配。

3、启用预览和缩略图传递

照片捕获系统支持预览和缩略图作为照片拍摄中全尺寸主图像的伴图。预览图用于立即显示:如在iOS 应用程序“相机”中拍摄时所见，因此可以在当前设备上进行全屏显示。缩略图用于嵌入输出图像文件中，并可由其他软件（例如文件浏览器中的快速查看）使用，以允许用户快速查看图像而无需加载整个图像文件。缩略图图像的大小可能会受到限制，具体取决于输出文件格式。

3.1、预览图

描述主照片的预览图的格式字典；默认情况为nil，指定AVCapturePhotoOutput应仅返回请求的主图。

@property(nonatomic, copy) NSDictionary<NSString *,id> *previewPhotoFormat;

要同时接收预览图，需要设置该字典为描述该图像格式的字典，其中包含以下键和值：

• 字典必须包含 kCVPixelBufferPixelFormatTypeKey 键，其对应值必须是 availablePreviewPhotoPixelFormatTypes 数组中列出的像素格式类型之一。
• 还可以包含 kCVPixelBufferWidthKey 和 kCVPixelBufferHeightKey 键以指定预览图的宽高。（如果指定宽度或高度，则必须同时指定两者。）如果指定的宽高与主照片的宽高比不匹配，则 AVCapturePhotoOutput 会提供一个预览图像，其大小与两个指定尺寸的长度相匹配，保留原始宽高比。

与照片设置兼容的像素格式类型数组，用于预览图；该数组的顺序是首先列出需要最少转换的格式。

@property(nonatomic, readonly) NSArray<NSNumber *> *availablePreviewPhotoPixelFormatTypes;

要启用预览图以及照片拍摄的主图，需要使用此数组中列出的 kCVPixelBufferPixelFormatTypeKey 值之一设置previewPhotoFormat 属性。

3.2、缩略图

描述主照片的缩略图的格式字典；默认情况为nil，指定AVCapturePhotoOutput不应在照片文件输出中嵌入缩略图。

@property(nonatomic, copy) NSDictionary<NSString *,id> *embeddedThumbnailPhotoFormat;

要启用嵌入缩略图，需要设置该字典为描述缩略图格式的字典，其中包含以下键和值：

• 字典必须包含键 AVVideoCodecKey ，其对应值必须是 availableEmbeddedThumbnailPhotoCodecTypes 数组中列出的像素格式类型之一。
• 还可以包含 AVVideoWidthKey 和 AVVideoHeightKey 键以指定缩略图的宽高。如果指定宽度或高度，则必须同时指定两者。如果指定的大小与主照片的宽高比不匹配，则 AVCapturePhotoOutput 提供的缩略图，其大小与两个指定尺寸的长度匹配，保留 原始宽高比。

与照片设置兼容的视频编解码器类型数组，用于嵌入缩略图。

@property(nonatomic, readonly) NSArray<AVVideoCodecType> *availableEmbeddedThumbnailPhotoCodecTypes;

要在 AVCapturePhotoOutput 中启用嵌入缩略图，需要此数组中列出的其中一种编解码器类型设置embeddedThumbnailPhotoFormat 属性。此数组的顺序是首先列出最向后兼容的编解码器。

3.3、原始缩略图

//与照片设置兼容的视频编解码器类型数组，用于在照片文件输出中嵌入原始缩略图图像。
@property(nonatomic, readonly) NSArray<AVVideoCodecType> *availableRawEmbeddedThumbnailPhotoCodecTypes;

//描述嵌入照片文件输出中的原始缩略图图像的传送格式的字典。
@property(nonatomic, copy) NSDictionary<NSString *,id> *rawEmbeddedThumbnailPhotoFormat;

4、配置照片设置

4.1、此次拍摄照片时的闪光灯模式

注意：使用AVCapturePhotoOutput类时，AVCaptureDevice 的 flashMode属性被替代。

设置拍摄照片时的闪光灯模式，默认为 AVCaptureFlashModeOff。

@property(nonatomic) AVCaptureFlashMode flashMode;

在静态场景，使用AVCaptureFlashModeAuto设置相当于测试AVCapturePhotoOutput的 isFlashScene属性（指示是否建议将闪光灯用于相机当前可见的场景），然后在请求捕获之前相应地设置照片设置输出的flashMode属性。但是，当请求捕获和相机硬件捕获图像时，可见场景可能会发生变化：自动设置可确保在捕获时正确启用或禁用闪光灯。捕获发生时，AVCapturePhotoCaptureDelegate方法接收AVCaptureResolvedPhotoSettings对象，其flashEnabled属性指示用于该捕获的闪光灯模式。

注意：当设备变得非常热时，闪光灯将暂时不可用，直到设备冷却下来。虽然闪光灯不可用，但AVCapturePhotoOutput的supportedFlashModes 属性仍会将 AVCaptureFlashModeOn 和 AVCaptureFlashModeAuto 选项报告为可用，因此即使闪光灯暂时不可用，我们仍可以在AVCapturePhotoSettings中启用闪光灯。
当AVCapturePhotoOutput调用AVCapturePhotoCaptureDelegate方法时，需要检查提供的AVCaptureResolvedPhotoSettings 的 flashEnabled 属性，以验证是否正在使用闪光灯。

指定闪光灯模式时，必须满足以下要求：

• 指定的模式必须存在于 AVCapturePhotoOutput 的 supportedFlashModes 数组中。
• 如果闪光模式为 AVCaptureFlashModeOn，则可能无法启用图像稳定功能；启用闪光灯优先于autoStillImageStabilizationEnabled设置。
  当调用- capturePhotoWithSettings:delegate:方法时，AVCapturePhotoOutput将验证这些要求。如果AVCapturePhotoSettings不符合这些要求，则该方法会引发异常。

4.2、是否启用自动图像稳定

本次拍摄照片是否使用自动图像稳定；默认设置为YES，除非正在拍摄RAW照片，因为RAW照片未经处理，图像稳定涉及处理的照片。

@property(nonatomic, getter=isAutoStillImageStabilizationEnabled) BOOL autoStillImageStabilizationEnabled;

启用此设置后，设备会在弱光条件下自动应用稳定功能以抵消手抖动。自动稳定始终包括数字图像稳定，并且还可以包括基于当前设备的光学镜头稳定。
自动图像稳定与AVCaptureFlashModeOn设置不兼容。如果明确启用闪光灯，则AVCapturePhotoOutput会忽略图像稳定设置，并且提供给AVCaptureResolvedPhotoSettings对象的stillImageStabilizationEnabled属性始终为NO。

4.3、最高分辨率

本次拍摄是否以活动设备和格式支持的最高分辨率捕获静止图像；默认为NO。

@property(nonatomic, getter=isHighResolutionPhotoEnabled) BOOL highResolutionPhotoEnabled;

如果为NO，则AVCapturePhotoOutput将提供具有源AVCaptureDevice对象的活动捕获格式activeFormat的formatDescription属性指定的维度的图像。但是，某些设备和捕获格式允许以高于其视频捕获分辨率捕获静态图像。要捕获静态照片的最高分辨率（由捕获格式activeFormat的highResolutionStillImageDimensions属性描述），请将此设置为YES。
如果连接到AVCaptureSession的任何输出启用了视频稳定（参考AVCaptureConnection的 preferredVideoStabilizationMode属性），则捕获的图像可能比最大静止图像尺寸小约10％。（此大小更改是视频稳定的效果，通过裁剪和旋转来查找运动图像中的稳定区域）检查AVCaptureResolvedPhotoSettings对象，以查找每个捕获的照片的实际尺寸。

4.4、是否启用双摄像头拍摄

用于确定在双摄像头设备是否从两个摄像头传送图像，默认为 NO。

@property(nonatomic, getter=isDualCameraDualPhotoDeliveryEnabled) BOOL dualCameraDualPhotoDeliveryEnabled;

如果为NO，并且AVCapturePhotoOutput配置了AVCaptureDeviceTypeBuiltInDualCamera类型的AVCaptureDevice，则AVCapturePhotoOutput会为每次捕获提供单个主照片图像。 （
如果为YES，则协议方法- captureOutput:didFinishProcessingPhoto:error:为每个主图像至少触发两次：一次用于远焦镜头拍摄图像，一次用于广角镜头拍摄图像。不使用双摄像头设备时将此属性设置为YES会引发异常。

4.5、是否合并双摄像头设备的数据

本次拍摄是否自动组合双摄像头设备的数据；默认设置为YES，除非正在拍摄RAW照片，因为RAW照片未经处理，图像稳定涉及处理的照片。

@property(nonatomic, getter=isAutoDualCameraFusionEnabled) BOOL autoDualCameraFusionEnabled;

启用此设置后，双摄像头设备会自动组合两个摄像头的样本，以生成更高质量的图像。仅当在支持的设备上使用AVCaptureDeviceTypeBuiltInDualCamera设备类型时，此属性才适用。
提示：图像处理，包括双摄像头融合，增加了拍摄时间。要以尽可能高的速度拍摄照片（如内置相机的连拍模式），需将autoDualCameraFusionEnabled和autoStillImageStabilizationEnabled属性设置为NO，将flashMode属性设置为AVCaptureFlashModeOff。

4.6、双摄像头拍摄的校准数据

用于确定双摄像头拍摄照片是否还提供相机校准数据；默认设置为NO。

@property(nonatomic, getter=isCameraCalibrationDataDeliveryEnabled) BOOL cameraCalibrationDataDeliveryEnabled;

如果为NO，并且dualCameraDualPhotoDeliveryEnabled设置为YES，则双照片捕获不会传送其他数据。
如果为YES，则双照片捕获的AVCapturePhoto结果包括描述每个摄像头的成像参数的AVCameraCalibrationData对象。该数据对于在结果图像上执行计算机视觉任务是有用的。

5、动态照片设置

5.1、动态照片存储路径设置

设置动态照片输出的URL；默认情况下，此属性的值为nil，禁用动态照片拍摄。

@property(nonatomic, copy) NSURL *livePhotoMovieFileURL;

启用动态照片拍摄，需要满足以下要求：

• AVCapturePhotoOutput 的livePhotoCaptureEnabled属性必须为YES，并且其livePhotoCaptureSuspended属性必须为NO。
• 指定的URL必须是应用程序沙箱中可访问位置的fileURL。
• 委托对象必须实现-captureOutput:didFinishProcessingLivePhotoToMovieFileAtURL:duration:photoDisplayTime:resolvedSettings:error: 协议方法。

当调用- capturePhotoWithSettings:delegate:方法时，AVCapturePhotoOutput将验证这些要求。如果AVCapturePhotoSettings不符合这些要求，则该方法会引发异常。

5.2、动态照片元数据

包含动态照片元数据的字典。

@property(nonatomic, copy) NSArray<AVMetadataItem *> *livePhotoMovieMetadata;

动态照片始终包含AVMetadataQuickTimeMetadataKeyContentIdentifier键，将动图与相应静止图像的kCGImagePropertyExifMakerNote属性中的类似标识符相关联。如果您指定自己的内容标识符，则照片捕获输出会自动生成唯一的内容标识符。仅当livePhotoMovieFileURL属性设置为非零时，此属性才适用。

5.3、动态照片编码

用于编码动态照片输出部分的视频编解码器。

@property(nonatomic, copy) AVVideoCodecType livePhotoVideoCodecType;

此值必须是AVCapturePhotoOutput的availableLivePhotoVideoCodecTypes数组中列出的视频编解码器类型之一。

AVVideoCodecType 使用typedef修饰的描述捕获的视频编解码器的常量。

常量	描述
AVVideoCodecTypeH264	H.264视频编解码器。
AVVideoCodecTypeHEVC	HEVC视频编解码器。
AVVideoCodecTypeJPEG	JPEG视频编解码器。
AVVideoCodecTypeAppleProRes422	Apple ProRes422视频编解码器。
AVVideoCodecTypeAppleProRes4444	Apple ProRes4444视频编解码器。
AVVideoCodecKey	用于访问用于对视频进行编码的编解码器名称的密钥。

对于AVVideoCodecKey，此键的值是NSString的一个实例，相当于CMVideoCodecType。 使用此键将视频压缩格式设置为H.264，HEVC或JPEG，具体取决于AVCaptureMovieFileOutput中可用的视频编解码器类型。通过咨询availableVideoCodecTypes检查可用的视频编解码器类型。

6、拍摄深度数据

用于确定AVCapturePhotoOutput是否与照片一起捕获深度数据；默认为NO，表示AVCapturePhotoOutput仅生成照片数据和元数据。

@property(nonatomic, getter=isDepthDataDeliveryEnabled) BOOL depthDataDeliveryEnabled;

如果为YES，则AVCapturePhotoOutput将记录每像素场景深度信息，并在AVCapturePhoto中提供AVDepthData对象。为拍摄照片请求启用深度捕获要求首先使用AVCapturePhotoSettings的depthDataDeliveryEnabled属性配置照片输出以进行深度捕获，否则会引发异常。
注意：在将结果传递给协议方法- captureOutput:didFinishProcessingPhoto:error:之前，启用深度捕获和照片捕获会增加大量处理时间。

一个布尔值，用于确定生成输出文件数据时是否包含使用照片捕获的任何深度数据；默认为YES。

@property(nonatomic) BOOL embedsDepthDataInPhoto;

当此属性为YES，并且使用depthDataDeliveryEnabled属性启用深度数据捕获时，AVCapturePhoto类在将照片数据展平为兼容文件格式的输出时将深度贴图包含为嵌入式附件。如果期望使用照片捕获深度数据但不在输出中包含深度数据，需将此属性设置为NO。

一个布尔值，用于确定是否平滑噪声并填充深度数据输出中的缺失值；默认为YES。

@property(nonatomic, getter=isDepthDataFiltered) BOOL depthDataFiltered;

当此属性为YES，并且深度数据捕获使用depthDataDeliveryEnabled属性启用时，捕获系统通过在先前和之间进行时间插值来平滑噪声并填充深度数据图中的缺失值（由低光或镜头遮挡引起）。 后续帧的捕获深度数据。
过滤深度数据使得将视觉效果应用于伴随图像更有用，但会改变数据，使其不再适合计算机视觉任务。（在未过滤的深度图中，缺失值表示为NaN。）

7、捕捉人像效果遮罩

指定是否应与照片一起捕捉纵向效果遮罩；默认值为NO。如果期望使用照片获得纵向效果遮罩，需设置为YES。

@property(nonatomic, getter=isPortraitEffectsMatteDeliveryEnabled) BOOL portraitEffectsMatteDeliveryEnabled;

如果portraitEffectsMatteDeliveryEnabled未设置为YES，或者没有实现协议方法- captureOutput:didFinishProcessingPhoto:error:，则抛出异常。
注意：纵向效果遮罩生成需要存在深度数据，因此还必须将depthDataDeliveryEnabled设置为YES。
将此属性设置为YES并不保证在生成的AVCapturePhoto中将出现肖像效果遮罩。遮罩主要用于改善图像上的肖像效果的渲染质量。如果照片的内容缺少明确的前景主题，则不会生成纵向效果遮罩，并且属性返回nil。将此属性设置为YES可能会为- captureOutput:didFinishProcessingPhoto:error:增加大量处理时间。

指定是否应将使用此照片的人像效果遮罩写入照片文件结构；默认值为YES。

@property(nonatomic) BOOL embedsPortraitEffectsMatteInPhoto;

当portraitEffectsMatteDeliveryEnabled设置为YES时，此属性指定是否应将包含的纵向效果遮罩写入生成的照片的内部文件结构。目前仅在HEIF和JPEG中支持纵向效果遮罩。如果portraitEffectsMatteDeliveryEnabled设置为NO，则忽略此属性。

8、嵌入元数据

要嵌入AVCapturePhotoOutput的元数据键和值的字典。

@property(nonatomic, copy) NSDictionary<NSString *,id> *metadata;

AVCapturePhotoOutput自动写入元数据，包括图像方向，EXIF相机属性和动态照片元数据，可以使用CGImageProperties 中列出的键和值覆盖这些值或指定其他元数据；使用任何其他键设置此属性会引发异常。

---

本文涉及到的更多信息请阅读：
点击阅读 AVCaptureDevice
点击阅读 AVCaptureSession
点击阅读 AVCapturePhotoOutput
点击阅读 AVCapturePhotoCaptureDelegate
点击阅读 AVCapturePhotoSettings
点击阅读 AVCaptureResolvedPhotoSettings
点击阅读 AVCapturePhoto