카메라 프레임 분석 효과Effects for analyzing camera frames

이 문서에서는 SceneAnalysisEffectFaceDetectionEffect 를 사용 하 여 미디어 캡처 미리 보기 스트림의 콘텐츠를 분석 하는 방법을 설명 합니다.This article describes how to use the SceneAnalysisEffect and the FaceDetectionEffect to analyze the content of the media capture preview stream.

장면 분석 효과Scene analysis effect

SceneAnalysisEffect 는 미디어 캡처 미리 보기 스트림의 비디오 프레임을 분석 하 고 캡처 결과를 개선 하는 처리 옵션을 권장 합니다.The SceneAnalysisEffect analyzes the video frames in the media capture preview stream and recommends processing options to improve the capture result. 현재이 효과는 HDR (High Dynamic Range) 처리를 사용 하 여 캡처를 향상할 수 있는지 검색 하는 것을 지원 합니다.Currently, the effect supports detecting whether the capture would be improved by using High Dynamic Range (HDR) processing.

HDR 사용을 권장 하는 경우 다음과 같은 방법으로이 작업을 수행할 수 있습니다.If the effect recommends using HDR, you can do this in the following ways:

장면 분석 네임 스페이스Scene analysis namespaces

장면 분석을 사용 하려면 앱이 기본 미디어 캡처에 필요한 네임 스페이스 외에도 다음 네임 스페이스를 포함 해야 합니다.To use scene analysis, your app must include the following namespaces in addition to the namespaces required for basic media capture.

using Windows.Media.Core;
using Windows.Media.Devices;

장면 분석 효과를 초기화 하 고 미리 보기 스트림에 추가 합니다.Initialize the scene analysis effect and add it to the preview stream

비디오 효과는 캡처 장치에서 효과를 초기화 하는 데 필요한 설정과 효과를 제어 하는 데 사용할 수 있는 효과 인스턴스를 제공 하는 효과 정의 인 두 개의 Api를 사용 하 여 구현 됩니다.Video effects are implemented using two APIs, an effect definition, which provides settings that the capture device needs to initialize the effect, and an effect instance, which can be used to control the effect. 코드 내의 여러 위치에서 효과 인스턴스에 액세스할 수 있으므로 일반적으로 개체를 보유 하는 멤버 변수를 선언 해야 합니다.Since you may want to access the effect instance from multiple places within your code, you should typically declare a member variable to hold the object.

private SceneAnalysisEffect _sceneAnalysisEffect;

앱에서 MediaCapture 개체를 초기화 한 후 SceneAnalysisEffectDefinition의 새 인스턴스를 만듭니다.In your app, after you have initialized the MediaCapture object, create a new instance of SceneAnalysisEffectDefinition.

MediaCapture 개체에서 AddVideoEffectAsync 를 호출 하 여 캡처 장치에 효과를 등록 하 고, SceneAnalysisEffectDefinition 를 제공 하 고, mediastreamtype VideoPreview 을 지정 하 여 효과를 캡처 스트림과 달리 비디오 미리 보기 스트림에 적용 해야 함을 표시 합니다.Register the effect with the capture device by calling AddVideoEffectAsync on your MediaCapture object, providing the SceneAnalysisEffectDefinition and specifying MediaStreamType.VideoPreview to indicate that the effect should be applied to the video preview stream, as opposed to the capture stream. AddVideoEffectAsync 는 추가 된 효과의 인스턴스를 반환 합니다.AddVideoEffectAsync returns an instance of the added effect. 이 메서드는 여러 효과 형식에 사용할 수 있으므로 반환 된 인스턴스를 SceneAnalysisEffect 개체로 캐스팅 해야 합니다.Because this method can be used with multiple effect types, you must cast the returned instance to a SceneAnalysisEffect object.

장면 분석의 결과를 수신 하려면 SceneAnalyzed 이벤트에 대 한 처리기를 등록 해야 합니다.To receive the results of the scene analysis, you must register a handler for the SceneAnalyzed event.

현재 장면 분석 효과는 높은 동적 범위 분석기만 포함 합니다.Currently, the scene analysis effect only includes the high dynamic range analyzer. 효과의 HighDynamicRangeControl를 true로 설정 하 여 HDR 분석을 사용 하도록 설정 합니다.Enable HDR analysis by setting the effect's HighDynamicRangeControl.Enabled to true.

// Create the definition
var definition = new SceneAnalysisEffectDefinition();

// Add the effect to the video record stream
_sceneAnalysisEffect = (SceneAnalysisEffect)await _mediaCapture.AddVideoEffectAsync(definition, MediaStreamType.VideoPreview);

// Subscribe to notifications about scene information
_sceneAnalysisEffect.SceneAnalyzed += SceneAnalysisEffect_SceneAnalyzed;

// Enable HDR analysis
_sceneAnalysisEffect.HighDynamicRangeAnalyzer.Enabled = true;

SceneAnalyzed 이벤트 처리기 구현Implement the SceneAnalyzed event handler

장면 분석의 결과는 SceneAnalyzed 이벤트 처리기에서 반환 됩니다.The results of the scene analysis are returned in the SceneAnalyzed event handler. 처리기에 전달 된 SceneAnalyzedEventArgs 개체에는 Highdynamicrangeoutput 개체가 있는 SceneAnalysisEffectFrame 개체가 있습니다.The SceneAnalyzedEventArgs object passed into the handler has a SceneAnalysisEffectFrame object which has a HighDynamicRangeOutput object. 높은 동적 범위 출력의 확신 속성은 0에서 1.0 사이의 값을 제공 합니다. 여기서 0은 hdr 처리가 캡처 결과를 개선 하는 데 도움이 되지 않으며 1.0은 hdr 처리가 도움이 됨을 나타냅니다.The Certainty property of the high dynamic range output provides a value between 0 and 1.0 where 0 indicates that HDR processing would not help improve the capture result and 1.0 indicates that HDR processing would help. 에서는 HDR를 사용 하거나 사용자에 게 결과를 표시 하 고 사용자가 결정 하도록 하는 임계값 지점을 결정할 수 있습니다.Your can decide the threshold point at which you want to use HDR or show the results to the user and let the user decide.

private void SceneAnalysisEffect_SceneAnalyzed(SceneAnalysisEffect sender, SceneAnalyzedEventArgs args)
{
    double hdrCertainty = args.ResultFrame.HighDynamicRange.Certainty;
    
    // Certainty value is between 0.0 and 1.0
    if(hdrCertainty > MyCertaintyCap)
    {
        ShowMessageToUser("Enabling HDR capture is recommended.");
    }
}

또한 처리기로 전달 되는 Highdynamicrangeoutput 개체에는 HDR 처리를 위한 변수 사진 시퀀스를 캡처하기 위한 제안 프레임 컨트롤러를 포함 하는 FrameControllers 속성이 있습니다.The HighDynamicRangeOutput object passed into the handler also has a FrameControllers property which contains suggested frame controllers for capturing a variable photo sequence for HDR processing. 자세한 내용은 변수 사진 시퀀스를 참조 하세요.For more information, see Variable photo sequence.

장면 분석 효과 정리Clean up the scene analysis effect

앱이 캡처를 완료 한 후에는 MediaCapture 개체를 삭제 하기 전에 효과의 Highdynamicrangeanalyzer 를 false로 설정 하 고 SceneAnalyzed 이벤트 처리기를 등록 취소 하 여 장면 분석 효과를 사용 하지 않도록 설정 해야 합니다.When your app is done capturing, before disposing of the MediaCapture object, you should disable the scene analysis effect by setting the effect's HighDynamicRangeAnalyzer.Enabled property to false and unregister your SceneAnalyzed event handler. MediaCapture를 호출 하 여 효과가 추가 된 스트림 이후 비디오 미리 보기 스트림을 지정 합니다 .Call MediaCapture.ClearEffectsAsync, specifying the video preview stream since that was the stream to which the effect was added. 마지막으로 멤버 변수를 null로 설정 합니다.Finally, set your member variable to null.

// Disable detection
_sceneAnalysisEffect.HighDynamicRangeAnalyzer.Enabled = false;

_sceneAnalysisEffect.SceneAnalyzed -= SceneAnalysisEffect_SceneAnalyzed;

// Remove the effect from the preview stream
await _mediaCapture.ClearEffectsAsync(MediaStreamType.VideoPreview);

// Clear the member variable that held the effect instance
_sceneAnalysisEffect = null;

얼굴 검색 효과Face detection effect

FaceDetectionEffect 는 미디어 캡처 미리 보기 스트림 내에서 얼굴의 위치를 식별 합니다.The FaceDetectionEffect identifies the location of faces within the media capture preview stream. 이 효과를 사용 하면 미리 보기 스트림에서 얼굴이 검색 될 때마다 알림을 받을 수 있으며 미리 보기 프레임 내에서 검색 된 각 면에 대 한 경계 상자를 제공할 수 있습니다.The effect allows you to receive a notification whenever a face is detected in the preview stream and provides the bounding box for each detected face within the preview frame. 지원 되는 장치에서 얼굴 검색 효과는 향상 된 노출을 제공 하며 장면의 가장 중요 한 면에 집중 합니다.On supported devices, the face detection effect also provides enhanced exposure and focus on the most important face in the scene.

얼굴 감지 네임 스페이스Face detection namespaces

얼굴 감지를 사용 하려면 앱이 기본 미디어 캡처에 필요한 네임 스페이스 외에도 다음 네임 스페이스를 포함 해야 합니다.To use face detection, your app must include the following namespaces in addition to the namespaces required for basic media capture.

using Windows.Media.Core;

얼굴 검색 효과를 초기화 하 고 미리 보기 스트림에 추가 합니다.Initialize the face detection effect and add it to the preview stream

비디오 효과는 캡처 장치에서 효과를 초기화 하는 데 필요한 설정과 효과를 제어 하는 데 사용할 수 있는 효과 인스턴스를 제공 하는 효과 정의 인 두 개의 Api를 사용 하 여 구현 됩니다.Video effects are implemented using two APIs, an effect definition, which provides settings that the capture device needs to initialize the effect, and an effect instance, which can be used to control the effect. 코드 내의 여러 위치에서 효과 인스턴스에 액세스할 수 있으므로 일반적으로 개체를 보유 하는 멤버 변수를 선언 해야 합니다.Since you may want to access the effect instance from multiple places within your code, you should typically declare a member variable to hold the object.

FaceDetectionEffect _faceDetectionEffect;

앱에서 MediaCapture 개체를 초기화 한 후 FaceDetectionEffectDefinition의 새 인스턴스를 만듭니다.In your app, after you have initialized the MediaCapture object, create a new instance of FaceDetectionEffectDefinition. DetectionMode 속성을 설정 하 여 더 빠른 얼굴 검색 또는 더 정확한 얼굴 검색의 우선 순위를 지정 합니다.Set the DetectionMode property to prioritize faster face detection or more accurate face detection. SynchronousDetectionEnabled 를 설정 하 여이 작업을 수행 하면 미리 보기 환경이 고르지 않을 수 있으므로 들어오는 프레임에서 얼굴 감지를 완료할 때까지 지연 되지 않도록 지정 합니다.Set SynchronousDetectionEnabled to specify that incoming frames are not delayed waiting for face detection to complete as this can result in a choppy preview experience.

MediaCapture 개체에서 AddVideoEffectAsync 를 호출 하 여 캡처 장치에 효과를 등록 하 고, FaceDetectionEffectDefinition 를 제공 하 고, mediastreamtype VideoPreview 을 지정 하 여 효과를 캡처 스트림과 달리 비디오 미리 보기 스트림에 적용 해야 함을 표시 합니다.Register the effect with the capture device by calling AddVideoEffectAsync on your MediaCapture object, providing the FaceDetectionEffectDefinition and specifying MediaStreamType.VideoPreview to indicate that the effect should be applied to the video preview stream, as opposed to the capture stream. AddVideoEffectAsync 는 추가 된 효과의 인스턴스를 반환 합니다.AddVideoEffectAsync returns an instance of the added effect. 이 메서드는 여러 효과 형식에 사용할 수 있으므로 반환 된 인스턴스를 FaceDetectionEffect 개체로 캐스팅 해야 합니다.Because this method can be used with multiple effect types, you must cast the returned instance to a FaceDetectionEffect object.

FaceDetectionEffect 속성을 설정 하 여 효과를 사용 하거나 사용 하지 않도록 설정 합니다.Enable or disable the effect by setting the FaceDetectionEffect.Enabled property. FaceDetectionEffect DesiredDetectionInterval 속성을 설정 하 여 효과에서 프레임을 분석 하는 빈도를 조정 합니다.Adjust how often the effect analyzes frames by setting the FaceDetectionEffect.DesiredDetectionInterval property. 미디어 캡처가 진행 중일 때 이러한 속성을 모두 조정할 수 있습니다.Both of these properties can be adjusted while media capture is ongoing.


// Create the definition, which will contain some initialization settings
var definition = new FaceDetectionEffectDefinition();

// To ensure preview smoothness, do not delay incoming samples
definition.SynchronousDetectionEnabled = false;

// In this scenario, choose detection speed over accuracy
definition.DetectionMode = FaceDetectionMode.HighPerformance;

// Add the effect to the preview stream
_faceDetectionEffect = (FaceDetectionEffect)await _mediaCapture.AddVideoEffectAsync(definition, MediaStreamType.VideoPreview);

// Choose the shortest interval between detection events
_faceDetectionEffect.DesiredDetectionInterval = TimeSpan.FromMilliseconds(33);

// Start detecting faces
_faceDetectionEffect.Enabled = true;

얼굴이 감지 되 면 알림 받기Receive notifications when faces are detected

비디오 미리 보기에서 검색 된 얼굴 주위의 상자를 그리는 등 얼굴 감지 시 일부 작업을 수행 하려는 경우 FaceDetected 이벤트를 등록할 수 있습니다.If you want to perform some action when faces are detected, such as drawing a box around detected faces in the video preview, you can register for the FaceDetected event.

// Register for face detection events
_faceDetectionEffect.FaceDetected += FaceDetectionEffect_FaceDetected;

이벤트에 대 한 처리기에서 FaceDetectedEventArgsFaceDetectionEffectFrame DetectedFaces 속성에 액세스 하 여 프레임에서 검색 된 모든 얼굴의 목록을 가져올 수 있습니다.In the handler for the event, you can get a list of all faces detected in a frame by accessing the FaceDetectionEffectFrame.DetectedFaces property of the FaceDetectedEventArgs. FaceBox 속성은 미리 보기 스트림 차원과 관련 하 여 검색 된 얼굴을 포함 하는 사각형을 설명 하는 BitmapBounds 구조체입니다.The FaceBox property is a BitmapBounds structure that describes the rectangle containing the detected face in units relative to the preview stream dimensions. 미리 보기 스트림 좌표를 화면 좌표로 변환 하는 샘플 코드를 보려면 face 검색 UWP 샘플을 참조 하세요.To view sample code that transforms the preview stream coordinates into screen coordinates, see the face detection UWP sample.

private void FaceDetectionEffect_FaceDetected(FaceDetectionEffect sender, FaceDetectedEventArgs args)
{
    foreach (Windows.Media.FaceAnalysis.DetectedFace face in args.ResultFrame.DetectedFaces)
    {
        BitmapBounds faceRect = face.FaceBox;

        // Draw a rectangle on the preview stream for each face
    }
}

얼굴 검색 효과 정리Clean up the face detection effect

앱이 캡처를 완료 한 후 MediaCapture 개체를 삭제 하기 전에 FaceDetectionEffect 를 사용 하 여 얼굴 검색 효과를 사용 하지 않도록 설정 하 고 이전에 등록 한 경우 FaceDetected 이벤트 처리기를 등록 취소 해야 합니다.When your app is done capturing, before disposing of the MediaCapture object, you should disable the face detection effect with FaceDetectionEffect.Enabled and unregister your FaceDetected event handler if you previously registered one. MediaCapture를 호출 하 여 효과가 추가 된 스트림 이후 비디오 미리 보기 스트림을 지정 합니다 .Call MediaCapture.ClearEffectsAsync, specifying the video preview stream since that was the stream to which the effect was added. 마지막으로 멤버 변수를 null로 설정 합니다.Finally, set your member variable to null.

// Disable detection
_faceDetectionEffect.Enabled = false;

// Unregister the event handler
_faceDetectionEffect.FaceDetected -= FaceDetectionEffect_FaceDetected;

// Remove the effect from the preview stream
await _mediaCapture.ClearEffectsAsync(MediaStreamType.VideoPreview);

// Clear the member variable that held the effect instance
_faceDetectionEffect = null;

검색 된 면에 대 한 포커스 및 노출이 지원 되는지 확인 합니다.Check for focus and exposure support for detected faces

모든 장치에는 검색 된 면에 따라 포커스 및 노출을 조정할 수 있는 캡처 장치가 없습니다.Not all devices have a capture device that can adjust its focus and exposure based on detected faces. 얼굴 검색은 장치 리소스를 사용 하므로,이 기능을 사용 하 여 캡처를 향상 시킬 수 있는 장치 에서만 얼굴 감지를 사용 하도록 설정할 수 있습니다.Because face detection consumes device resources, you may only want to enable face detection on devices that can use the feature to enhance capture. 얼굴 기반 캡처 최적화를 사용할 수 있는지 확인 하려면 초기화 된 MediaCapture 에 대 한 VideoDeviceController 을 가져온 다음 비디오 장치 컨트롤러의 RegionsOfInterestControl를 가져옵니다.To see if face-based capture optimization is available, get the VideoDeviceController for your initialized MediaCapture and then get the video device controller's RegionsOfInterestControl. Maxregions 하나 이상의 지역을 지원 하는지 확인 하세요.Check to see if the MaxRegions supports at least one region. 그런 다음 AutoExposureSupported 또는 AutoFocusSupported 가 true 인지 확인 합니다.Then check to see if either AutoExposureSupported or AutoFocusSupported are true. 이러한 조건이 충족 되 면 장치에서 얼굴 감지를 활용 하 여 캡처를 향상 시킬 수 있습니다.If these conditions are met, then the device can take advantage of face detection to enhance capture.

var regionsControl = _mediaCapture.VideoDeviceController.RegionsOfInterestControl;
bool faceDetectionFocusAndExposureSupported =
    regionsControl.MaxRegions > 0 &&
    (regionsControl.AutoExposureSupported || regionsControl.AutoFocusSupported);