Yüz Dedektörü görevi, bir resimdeki veya videodaki yüzleri algılamanıza olanak tanır. Yüzleri ve yüz özelliklerini bir çerçeve içindeki yerini belirlemek için bu görevi kullanabilirsiniz. Bu görev, tek görüntülerle veya sürekli bir görüntü akışıyla çalışan bir makine öğrenimi (ML) modeli kullanır. Görev, yüzdeki şu önemli noktaların yanı sıra yüz konumlarını ortaya çıkarır: sol göz, sağ göz, burun ucu, ağız, sol göz trajyonu ve sağ göz trajyonu.
Bu talimatlarda açıklanan kod örneğine GitHub'dan ulaşabilirsiniz. Bu web demosunu izleyerek bu görevi çalışırken görebilirsiniz. Bu görevin özellikleri, modelleri ve yapılandırma seçenekleri hakkında daha fazla bilgi edinmek için Genel Bakış sayfasını inceleyin.
Kod örneği
MediaPipe Tasks örnek kodu, iOS için bir Yüz Dedektörü uygulamasının basit bir uygulamasıdır. Örnekte, kesintisiz bir video akışındaki yüzlerin algılanması için fiziksel bir Android cihazın kamerası kullanılmaktadır. Uygulama, cihaz galerisindeki resim ve videolardaki yüzleri de algılayabilir.
Uygulamayı kendi iOS uygulamanız için başlangıç noktası olarak kullanabilir veya mevcut bir uygulamayı değiştirirken referans olarak kullanabilirsiniz. Yüz Dedektörü örnek kodu GitHub'da barındırılır.
Kodu indirme
Aşağıdaki talimatlar, git komut satırı aracını kullanarak örnek kodun yerel bir kopyasını nasıl oluşturacağınızı göstermektedir.
Örnek kodu indirmek için:
Aşağıdaki komutu kullanarak git deposunu klonlayın:
git clone https://github.com/google-ai-edge/mediapipe-samples
İsteğe bağlı olarak, git örneğinizi az ödeme yöntemini kullanacak şekilde yapılandırın. Böylece yalnızca Yüz Algılama örnek uygulamasına ait dosyalara sahip olursunuz:
cd mediapipe git sparse-checkout init --cone git sparse-checkout set examples/face_detector/ios/
Örnek kodun yerel sürümünü oluşturduktan sonra MediaPipe görev kitaplığını yükleyebilir, Xcode kullanarak projeyi açabilir ve uygulamayı çalıştırabilirsiniz. Talimatlar için iOS için Kurulum Kılavuzu'na bakın.
Temel bileşenler
Aşağıdaki dosyalar, Yüz Dedektörü örnek uygulaması için önemli kodu içerir:
- FaceDetectorService.swift: Algılayıcıyı başlatır, model seçimini işler ve giriş verilerinde çıkarım yürütür.
- CameraViewController: Canlı kamera feed'i giriş modu için kullanıcı arayüzünü uygular ve algılama sonuçlarını görselleştirir.
- MediaLibraryViewController.swift: Hareketsiz resim ve video dosyası giriş modu için kullanıcı arayüzünü uygular ve algılama sonuçlarını görselleştirir.
Kurulum
Bu bölümde, geliştirme ortamınızı kurmayla ilgili temel adımlar ve Yüz Dedektörü'nü kullanmak için proje kodlama açıklanmaktadır. Platform sürümü gereksinimleri de dahil olmak üzere, MediaPipe görevlerini kullanmak amacıyla geliştirme ortamınızı ayarlama hakkında genel bilgiler için iOS için kurulum kılavuzuna bakın.
Bağımlılıklar
Yüz Dedektörü, CocoaPods ile yüklenmesi gereken MediaPipeTasksVision
kitaplığını kullanır. Kitaplık hem Swift hem de Objective-C uygulamalarıyla uyumludur ve dile özgü ek kurulum gerektirmez.
CocoaPods'u macOS'e yükleme talimatları için CocoaPods yükleme kılavuzuna bakın.
Uygulamanız için gerekli kapsüllerle Podfile
oluşturma talimatları için CocoaPods'u kullanma bölümüne bakın.
Aşağıdaki kodu kullanarak MediaPipeTasksVision kapsülünü Podfile
içine ekleyin:
target 'MyFaceDetectorApp' do
use_frameworks!
pod 'MediaPipeTasksVision'
end
Uygulamanız birim test hedefleri içeriyorsa Podfile
cihazınızın kurulumuyla ilgili ek bilgiler için iOS için Kurulum Kılavuzu'na bakın.
Model
MediaPipe Yüz Dedektörü görevi, bu görevle uyumlu, eğitilmiş bir model gerektirir. Yüz Dedektörü için eğitilmiş modeller hakkında daha fazla bilgi edinmek üzere göreve genel bakış Modeller bölümüne bakın.
Bir model seçip indirin ve Xcode kullanarak proje dizininize ekleyin. Xcode projenize dosya ekleme talimatları için Xcode projenizde dosya ve klasörleri yönetme bölümüne bakın.
Uygulama paketinizdeki modelin yolunu belirtmek için BaseOptions.modelAssetPath
özelliğini kullanın. Kod örneği için sonraki bölüme bakın.
Görevi oluşturma
Yüz Dedektörü görevini, başlatıcılardan birini çağırarak oluşturabilirsiniz. FaceDetector(options:)
başlatıcısı, yapılandırma seçenekleri için değerleri kabul eder.
Özelleştirilmiş yapılandırma seçenekleriyle başlatılan bir Yüz Dedektörü'ne ihtiyacınız yoksa varsayılan seçeneklerle bir Yüz Dedektörü oluşturmak için FaceDetector(modelPath:)
başlatıcısını kullanabilirsiniz. Yapılandırma seçenekleri hakkında daha fazla bilgi için Yapılandırmaya Genel Bakış bölümüne bakın.
Yüz Dedektörü görevi 3 giriş veri türünü destekler: hareketsiz resimler, video dosyaları ve canlı video akışları. Varsayılan olarak FaceDetector(modelPath:)
, hareketsiz resimler için bir görev başlatır. Görevinizin video dosyalarını veya canlı video akışlarını işlemek için başlatılmasını istiyorsanız videoyu veya canlı yayın çalışma modunu belirtmek için FaceDetector(options:)
öğesini kullanın. Canlı yayın modu, Yüz Algılayıcı'nın yüz algılama sonuçlarını yetki verdiğiniz kişiye eşzamansız olarak sunmasını sağlayan ek faceDetectorLiveStreamDelegate
yapılandırma seçeneğini de gerektirir.
Görevi nasıl oluşturacağınızı ve çıkarımda bulunacağınızı görmek için koşu modunuza karşılık gelen sekmeyi seçin.
Swift
Resim
import MediaPipeTasksVision let modelPath = Bundle.main.path(forResource: "model", ofType: "tflite") let options = FaceDetectorOptions() options.baseOptions.modelAssetPath = modelPath options.runningMode = .image let faceDetector = try FaceDetector(options: options)
Video
import MediaPipeTasksVision let modelPath = Bundle.main.path(forResource: "model", ofType: "tflite") let options = FaceDetectorOptions() options.baseOptions.modelAssetPath = modelPath options.runningMode = .video let faceDetector = try FaceDetector(options: options)
Canlı yayın
import MediaPipeTasksVision // Class that conforms to the `FaceDetectorLiveStreamDelegate` protocol and // implements the method that the face detector calls once it finishes // detecting faces in each input frame. class FaceDetectorResultProcessor: NSObject, FaceDetectorLiveStreamDelegate { func faceDetector( _ faceDetector: FaceDetector, didFinishDetection result: FaceDetectorResult?, timestampInMilliseconds: Int, error: Error?) { // Process the face detection result or errors here. } } let modelPath = Bundle.main.path( forResource: "model", ofType: "tflite") let options = FaceDetectorOptions() options.baseOptions.modelAssetPath = modelPath options.runningMode = .liveStream // Assign an object of the class to the `faceDetectorLiveStreamDelegate` // property. let processor = FaceDetectorResultProcessor() options.faceDetectorLiveStreamDelegate = processor let faceDetector = try FaceDetector(options: options)
Objective-C
Resim
@import MediaPipeTasksVision; NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"model" ofType:@"tflite"]; MPPFaceDetectorOptions *options = [[MPPFaceDetectorOptions alloc] init]; options.baseOptions.modelAssetPath = modelPath; options.runningMode = MPPRunningModeImage; MPPFaceDetector *faceDetector = [[MPPFaceDetector alloc] initWithOptions:options error:nil];
Video
@import MediaPipeTasksVision; NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"model" ofType:@"tflite"]; MPPFaceDetectorOptions *options = [[MPPFaceDetectorOptions alloc] init]; options.baseOptions.modelAssetPath = modelPath; options.runningMode = MPPRunningModeVideo; MPPFaceDetector *faceDetector = [[MPPFaceDetector alloc] initWithOptions:options error:nil];
Canlı yayın
@import MediaPipeTasksVision; // Class that conforms to the `MPPFaceDetectorLiveStreamDelegate` protocol // and implements the method that the face detector calls once it finishes // detecting faces in each input frame. @interface APPFaceDetectorResultProcessor : NSObject@end @implementation APPFaceDetectorResultProcessor - (void)faceDetector:(MPPFaceDetector *)faceDetector didFinishDetectionWithResult:(MPPFaceDetectorResult *)faceDetectorResult timestampInMilliseconds:(NSInteger)timestampInMilliseconds error:(NSError *)error { // Process the face detector result or errors here. } @end NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"model" ofType:@"tflite"]; MPPFaceDetectorOptions *options = [[MPPFaceDetectorOptions alloc] init]; options.baseOptions.modelAssetPath = modelPath; options.runningMode = MPPRunningModeLiveStream; // Assign an object of the class to the `faceDetectorLiveStreamDelegate` // property. APPFaceDetectorResultProcessor *processor = [APPFaceDetectorResultProcessor new]; options.faceDetectorLiveStreamDelegate = processor; MPPFaceDetector *faceDetector = [[MPPFaceDetector alloc] initWithOptions:options error:nil];
Not: Video modunu veya canlı yayın modunu kullanırsanız Yüz Dedektörü, her karede algılama modelinin tetiklenmesini önlemek için izleme özelliğini kullanarak gecikmenin azaltılmasına yardımcı olur.
Yapılandırma seçenekleri
Bu görev, iOS uygulamaları için aşağıdaki yapılandırma seçeneklerine sahiptir:
Seçenek Adı | Açıklama | Değer Aralığı | Varsayılan Değer |
---|---|---|---|
runningMode |
Görevin çalışma modunu ayarlar. Üç mod vardır: RESİM: Tek resimli girişler için mod. VİDEO: Bir videonun kodu çözülmüş karelerine yönelik mod. LIVE_STREAM: Kamera gibi giriş verilerini içeren bir canlı yayın modu. Bu modda, sonuçları eşzamansız olarak almak üzere bir işleyici ayarlamak için resultListener çağrılmalıdır. |
{RunningMode.image, RunningMode.video, RunningMode.liveStream } |
RunningMode.image |
minDetectionConfidence |
Yüz algılamanın başarılı olarak kabul edilmesi için gereken minimum güven puanı. | Float [0,1] |
0.5 |
minSuppressionThreshold |
Yüz algılamanın çakıştığı kabul edilmesi için maksimum olmayan minimum engelleme eşiği. | Float [0,1] |
0.3 |
Canlı yayın yapılandırması
Çalışma modu canlı yayın olarak ayarlandığında Yüz Algılayıcısı için ek faceDetectorLiveStreamDelegate
yapılandırma seçeneği gerekir. Bu seçenek, yüz algılayıcının algılama sonuçlarını eşzamansız olarak sunmasını sağlar. Yetki verilen kullanıcı, Yüz Dedektörü'nün her kare için yüz algılama sonuçlarını işledikten sonra çağırdığı faceDetector(_:didFinishDetection:timestampInMilliseconds:error:)
yöntemini uygular.
Seçenek adı | Açıklama | Değer Aralığı | Varsayılan Değer |
---|---|---|---|
faceDetectorLiveStreamDelegate |
Yüz Dedektörünün, canlı yayın modunda eşzamansız olarak yüz algılama sonuçlarını
almasını sağlar. Örneği bu mülke ayarlanan sınıf, faceDetector(_:didFinishDetection:timestampInMilliseconds:error:) yöntemini uygulamalıdır. |
Geçerli değil | Belirlenmedi |
Verileri hazırlama
Yüz Dedektörü'ne iletmeden önce giriş resmini veya çerçevesini bir MPImage
nesnesine dönüştürmeniz gerekir. MPImage
, farklı iOS görüntü biçimlerini destekler ve çıkarım için bunları herhangi bir çalışma modunda kullanabilir. MPImage
hakkında daha fazla bilgi için MPImage API'yi inceleyin.
Kullanım alanınıza ve uygulamanızın gerektirdiği çalışma moduna göre bir iOS görüntü biçimi seçin.MPImage
; UIImage
, CVPixelBuffer
ve CMSampleBuffer
iOS görüntü biçimlerini kabul eder.
UIImage
UIImage
biçimi, aşağıdaki çalıştırma modları için uygundur:
Resimler: bir uygulama paketi, kullanıcı galerisi veya dosya sisteminden
UIImage
olarak biçimlendirilmiş resimlerMPImage
nesnesine dönüştürülebilir.Videolar: AVAssetImageGenerator kullanarak video karelerini CGImage biçiminde ayıklayın ve
UIImage
görüntülerine dönüştürün.
Swift
// Load an image on the user's device as an iOS `UIImage` object. // Convert the `UIImage` object to a MediaPipe's Image object having the default // orientation `UIImage.Orientation.up`. let image = try MPImage(uiImage: image)
Objective-C
// Load an image on the user's device as an iOS `UIImage` object. // Convert the `UIImage` object to a MediaPipe's Image object having the default // orientation `UIImageOrientationUp`. MPImage *image = [[MPPImage alloc] initWithUIImage:image error:nil];
Örnekte, varsayılan UIImage.Orientation.Up yönle bir MPImage
başlatılır. Desteklenen UIImage.Orientation değerlerinden herhangi biriyle bir MPImage
başlatabilirsiniz. Yüz Dedektörü; .upMirrored
, .downMirrored
, .leftMirrored
, .rightMirrored
gibi yansıtılmış yönleri desteklemez.
UIImage
hakkında daha fazla bilgi için UIImage Apple Developer
Dokümanlar'a bakın.
CVPixelBuffer
CVPixelBuffer
biçimi, çerçeveler oluşturan ve işleme amacıyla iOS CoreImage çerçevesini kullanan uygulamalar için uygundur.
CVPixelBuffer
biçimi, aşağıdaki çalıştırma modları için uygundur:
Resimler: iOS'in
CoreImage
çerçevesini kullanarak bir miktar işlemden sonraCVPixelBuffer
resim oluşturan uygulamalar, resim çalıştırma modunda Yüz Algılayıcı'ya gönderilebilir.Videolar: Video kareleri, işlenmek üzere
CVPixelBuffer
biçimine dönüştürülebilir ve ardından video modunda Yüz Algılayıcı'ya gönderilebilir.Canlı yayın: Kare oluşturmak için iOS kamera kullanan uygulamalar, canlı yayın modunda Yüz Algılayıcı'ya gönderilmeden önce işlenmek üzere
CVPixelBuffer
biçimine dönüştürülebilir.
Swift
// Obtain a CVPixelBuffer. // Convert the `CVPixelBuffer` object to a MediaPipe's Image object having the default // orientation `UIImage.Orientation.up`. let image = try MPImage(pixelBuffer: pixelBuffer)
Objective-C
// Obtain a CVPixelBuffer. // Convert the `CVPixelBuffer` object to a MediaPipe's Image object having the // default orientation `UIImageOrientationUp`. MPImage *image = [[MPPImage alloc] initWithUIImage:image error:nil];
CVPixelBuffer
hakkında daha fazla bilgi için CVPixelBuffer Apple Geliştirici
Dokümanları'na bakın.
CMSampleBuffer
CMSampleBuffer
biçimi, tek tip bir medya türünün medya örneklerini depolar ve canlı yayın çalıştırma modu için çok uygundur. iOS kameralardan alınan canlı kareler, iOS AVCaptureVideoDataOutput tarafından eşzamansız olarak CMSampleBuffer
biçiminde yayınlanır.
Swift
// Obtain a CMSampleBuffer. // Convert the `CMSampleBuffer` object to a MediaPipe's Image object having the default // orientation `UIImage.Orientation.up`. let image = try MPImage(sampleBuffer: sampleBuffer)
Objective-C
// Obtain a `CMSampleBuffer`. // Convert the `CMSampleBuffer` object to a MediaPipe's Image object having the // default orientation `UIImageOrientationUp`. MPImage *image = [[MPPImage alloc] initWithSampleBuffer:sampleBuffer error:nil];
CMSampleBuffer
hakkında daha fazla bilgi için CMSampleBuffer Apple Geliştirici
Dokümanları'na bakın.
Görevi çalıştırma
Yüz Dedektörü'nü çalıştırmak için atanan çalışma moduna özel detect()
yöntemini kullanın:
- Hareketsiz resim:
detect(image:)
- Video:
detect(videoFrame:timestampInMilliseconds:)
- Canlı yayın:
detectAsync(image:timestampInMilliseconds:)
Yüz Dedektörü, giriş resminde veya çerçevesinde algılanan yüzleri döndürür.
Aşağıdaki kod örnekleri, Yüz Dedektörü'nün farklı çalışan modlarında nasıl çalıştırılacağına dair basit örnekler gösterir:
Swift
Resim
let result = try faceDetector.detect(image: image)
Video
let result = try faceDetector.detect( videoFrame: image, timestampInMilliseconds: timestamp)
Canlı yayın
try faceDetector.detectAsync( image: image, timestampInMilliseconds: timestamp)
Objective-C
Resim
MPPFaceDetectorResult *result = [faceDetector detectInImage:image error:nil];
Video
MPPFaceDetectorResult *result = [faceDetector detectInVideoFrame:image timestampInMilliseconds:timestamp error:nil];
Canlı yayın
BOOL success = [faceDetector detectAsyncInImage:image timestampInMilliseconds:timestamp error:nil];
Yüz Algılama kod örneğinde bu modların her biri detect(image:)
, detect(videoFrame:timestampInMilliseconds:)
ve detectAsync(image:timestampInMilliseconds:)
uygulama şekillerini daha ayrıntılı olarak göstermektedir. Örnek kod, kullanıcının, kullanım alanınız için gerekli olmayabilecek işleme modları arasında geçiş yapmasını sağlar.
Aşağıdakileri göz önünde bulundurun:
Video modunda veya canlı yayın modunda çalışırken Yüz Algılayıcı görevine giriş karesinin zaman damgasını da sağlamanız gerekir.
Yüz Dedektörü görevi, resim veya video modunda çalışırken giriş resmini veya çerçevesini işlemeyi bitirene kadar mevcut iş parçacığını engeller. Mevcut iş parçacığının engellenmesini önlemek için işlemeyi iOS Dispatch veya NSOperation çerçevelerini kullanarak bir arka plan iş parçacığında yürütün.
Canlı yayın modunda çalışırken Yüz Dedektörü görevi hemen geri gelir ve mevcut ileti dizisini engellemez. Her bir giriş çerçevesini işledikten sonra yüz algılama sonucuyla birlikte
faceDetector(_:didFinishDetection:timestampInMilliseconds:error:)
yöntemini çağırır. Yüz Algılayıcı, bu yöntemi özel bir seri gönderme sırasında eşzamansız olarak çağırır. Sonuçları kullanıcı arayüzünde görüntülemek için işlendikten sonra sonuçları ana sıraya gönderin. Yüz Dedektörü görevi başka bir kareyi işlemekle meşgulkendetectAsync
işlevi çağrılırsa Yüz Dedektörü yeni giriş çerçevesini yoksayar.
Sonuçları işleme ve görüntüleme
Çıkarım çalıştırıldığında, Yüz Dedektörü görevi algılanan yüzler için sınırlayıcı kutuları ve algılanan her yüz için güven puanını içeren bir FaceDetectorResult
nesnesi döndürür.
Aşağıda, bu görevden alınan çıkış verilerinin bir örneği gösterilmektedir:
FaceDetectionResult:
Detections:
Detection #0:
BoundingBox:
origin_x: 126
origin_y: 100
width: 463
height: 463
Categories:
Category #0:
index: 0
score: 0.9729152917861938
NormalizedKeypoints:
NormalizedKeypoint #0:
x: 0.18298381567001343
y: 0.2961040139198303
NormalizedKeypoint #1:
x: 0.3302789330482483
y: 0.29289937019348145
... (6 keypoints for each face)
Detection #1:
BoundingBox:
origin_x: 616
origin_y: 193
width: 430
height: 430
Categories:
Category #0:
index: 0
score: 0.9251380562782288
NormalizedKeypoints:
NormalizedKeypoint #0:
x: 0.6151331663131714
y: 0.3713381886482239
NormalizedKeypoint #1:
x: 0.7460576295852661
y: 0.38825345039367676
... (6 keypoints for each face)
Aşağıdaki resimde, görev çıkışının görseli gösterilmektedir:
Sınırlayıcı kutusu olmayan resim için orijinal resme bakın.
Yüz Dedektörü örnek kodu, sonuçların nasıl görüntüleneceğini gösterir. Ayrıntılar için kod örneğine bakın.