برچسب گذاری تصاویر با یک مدل سفارشی در iOS

شما می توانید از کیت ML برای شناسایی موجودیت ها در یک تصویر و برچسب گذاری آنها استفاده کنید. این API از طیف گسترده ای از مدل های طبقه بندی تصاویر سفارشی پشتیبانی می کند. لطفاً برای راهنمایی در مورد الزامات سازگاری مدل، مکان یافتن مدل های از پیش آموزش دیده و نحوه آموزش مدل های خود به مدل های سفارشی با کیت ML مراجعه کنید.

دو راه برای ادغام یک مدل سفارشی وجود دارد. می‌توانید با قرار دادن آن در پوشه دارایی برنامه خود، مدل را باندل کنید یا می‌توانید به صورت پویا آن را از Firebase دانلود کنید. جدول زیر این دو گزینه را با هم مقایسه می کند.

مدل همراه	مدل میزبانی شده
این مدل بخشی از APK برنامه شما است که اندازه آن را افزایش می دهد.	مدل بخشی از APK شما نیست. با آپلود در Firebase Machine Learning میزبانی می شود.
این مدل بلافاصله در دسترس است، حتی زمانی که دستگاه اندروید آفلاین است	مدل در صورت تقاضا دانلود می شود
بدون نیاز به پروژه Firebase	به پروژه Firebase نیاز دارد
برای به‌روزرسانی مدل، باید برنامه خود را دوباره منتشر کنید	به روز رسانی مدل را بدون انتشار مجدد برنامه خود فشار دهید
بدون تست A/B داخلی	تست آسان A/B با Firebase Remote Config

توجه: APIهای ML Kit iOS فقط روی دستگاه‌های 64 بیتی اجرا می‌شوند. اگر برنامه خود را با پشتیبانی 32 بیتی می‌سازید، قبل از استفاده از این API، معماری دستگاه را بررسی کنید.

آن را امتحان کنید

• برای مثالی از استفاده از مدل همراه، برنامه راه اندازی سریع چشم انداز و برای مثال استفاده از مدل میزبانی شده ، برنامه شروع سریع automl را ببینید.

قبل از اینکه شروع کنی

1. کتابخانه های ML Kit را در پادفایل خود قرار دهید:

   برای بسته‌بندی یک مدل با برنامه‌تان:

   pod 'GoogleMLKit/ImageLabelingCustom', '3.2.0'
   

   برای دانلود پویا یک مدل از Firebase، وابستگی LinkFirebase را اضافه کنید:

   pod 'GoogleMLKit/ImageLabelingCustom', '3.2.0'
   pod 'GoogleMLKit/LinkFirebase', '3.2.0'
   

2. پس از نصب یا به روز رسانی Pods پروژه خود، پروژه Xcode خود را با استفاده از .xcworkspace آن باز کنید. ML Kit در Xcode نسخه 13.2.1 یا بالاتر پشتیبانی می شود.

3. اگر می‌خواهید مدلی را دانلود کنید ، مطمئن شوید که Firebase را به پروژه iOS خود اضافه کرده‌اید ، اگر قبلاً این کار را انجام نداده‌اید. هنگامی که مدل را بسته بندی می کنید، این مورد نیاز نیست.

1. مدل را بارگذاری کنید

یک منبع مدل محلی را پیکربندی کنید

برای بسته‌بندی مدل با برنامه‌تان:

1. فایل مدل (معمولاً به .tflite یا .lite ختم می شود) را در پروژه Xcode خود کپی کنید، مراقب باشید که هنگام انجام این کار Copy bundle resources را انتخاب کنید. فایل مدل در بسته برنامه گنجانده شده و در ML Kit در دسترس خواهد بود.

2. شی LocalModel ایجاد کنید، مسیر فایل مدل را مشخص کنید:

   سریع

   let localModel = LocalModel(path: localModelFilePath)

   هدف-C

   MLKLocalModel *localModel =
       [[MLKLocalModel alloc] initWithPath:localModelFilePath];

توجه: اگر مدلی دارید که با AutoML Vision Edge در Firebase (نه Google Cloud) آموزش داده شده است، ممکن است موارد بالا کار نکنند. لطفاً راهنمای مهاجرت را برای دستورالعمل ها دنبال کنید.

یک منبع مدل میزبانی شده توسط Firebase را پیکربندی کنید

برای استفاده از مدل میزبانی از راه دور، یک شی RemoteModel ایجاد کنید و نامی را که به مدل اختصاص داده اید هنگام انتشار آن مشخص کنید:

سریع

let firebaseModelSource = FirebaseModelSource(
    name: "your_remote_model") // The name you assigned in
                               // the Firebase console.
let remoteModel = CustomRemoteModel(remoteModelSource: firebaseModelSource)

هدف-C

MLKFirebaseModelSource *firebaseModelSource =
    [[MLKFirebaseModelSource alloc]
        initWithName:@"your_remote_model"]; // The name you assigned in
                                            // the Firebase console.
MLKCustomRemoteModel *remoteModel =
    [[MLKCustomRemoteModel alloc]
        initWithRemoteModelSource:firebaseModelSource];

سپس، با مشخص کردن شرایطی که می‌خواهید اجازه دانلود را بدهید، کار دانلود مدل را شروع کنید. اگر مدل در دستگاه نباشد، یا اگر نسخه جدیدتری از مدل موجود باشد، این کار به صورت ناهمزمان مدل را از Firebase دانلود می‌کند:

سریع

let downloadConditions = ModelDownloadConditions(
  allowsCellularAccess: true,
  allowsBackgroundDownloading: true
)

let downloadProgress = ModelManager.modelManager().download(
  remoteModel,
  conditions: downloadConditions
)

هدف-C

MLKModelDownloadConditions *downloadConditions =
    [[MLKModelDownloadConditions alloc] initWithAllowsCellularAccess:YES
                                         allowsBackgroundDownloading:YES];

NSProgress *downloadProgress =
    [[MLKModelManager modelManager] downloadModel:remoteModel
                                       conditions:downloadConditions];

بسیاری از برنامه‌ها وظیفه دانلود را در کد اولیه خود شروع می‌کنند، اما شما می‌توانید این کار را در هر زمانی قبل از نیاز به استفاده از مدل انجام دهید.

برچسب‌گذار تصویر را پیکربندی کنید

پس از پیکربندی منابع مدل خود، یک شی ImageLabeler از یکی از آنها ایجاد کنید.

گزینه های ذیل در دسترس هستند:

گزینه ها
confidenceThreshold	حداقل امتیاز اطمینان برچسب های شناسایی شده اگر تنظیم نشود، از هر آستانه طبقه‌بندی‌کننده‌ای که توسط فراداده مدل مشخص شده است استفاده می‌شود. اگر مدل حاوی هیچ ابرداده ای نباشد یا ابرداده آستانه طبقه بندی کننده را مشخص نکرده باشد، از آستانه پیش فرض 0.0 استفاده می شود.
maxResultCount	حداکثر تعداد برچسب برای بازگشت. اگر تنظیم نشود، مقدار پیش فرض 10 استفاده می شود.

اگر فقط یک مدل باندل محلی دارید، فقط یک برچسب از شی LocalModel خود ایجاد کنید:

سریع

let options = CustomImageLabelerOptions(localModel: localModel)
options.confidenceThreshold = NSNumber(value: 0.0)
let imageLabeler = ImageLabeler.imageLabeler(options: options)

هدف-C

MLKCustomImageLabelerOptions *options =
    [[MLKCustomImageLabelerOptions alloc] initWithLocalModel:localModel];
options.confidenceThreshold = @(0.0);
MLKImageLabeler *imageLabeler =
    [MLKImageLabeler imageLabelerWithOptions:options];

اگر یک مدل با میزبانی از راه دور دارید، قبل از اجرای آن باید بررسی کنید که دانلود شده است. با استفاده از روش isModelDownloaded(remoteModel:) مدیر مدل می توانید وضعیت وظیفه دانلود مدل را بررسی کنید.

اگرچه شما فقط باید قبل از اجرای برچسب‌گذار این موضوع را تأیید کنید، اگر هم یک مدل با میزبانی از راه دور و هم یک مدل همراه با محلی دارید، ممکن است این بررسی را هنگام نمونه‌برداری از ImageLabeler انجام دهید: اگر یک برچسب‌گذاری از مدل راه دور ایجاد کنید. دانلود شده است، و در غیر این صورت از مدل محلی.

سریع

var options: CustomImageLabelerOptions!
if (ModelManager.modelManager().isModelDownloaded(remoteModel)) {
  options = CustomImageLabelerOptions(remoteModel: remoteModel)
} else {
  options = CustomImageLabelerOptions(localModel: localModel)
}
options.confidenceThreshold = NSNumber(value: 0.0)
let imageLabeler = ImageLabeler.imageLabeler(options: options)

هدف-C

MLKCustomImageLabelerOptions *options;
if ([[MLKModelManager modelManager] isModelDownloaded:remoteModel]) {
  options = [[MLKCustomImageLabelerOptions alloc] initWithRemoteModel:remoteModel];
} else {
  options = [[MLKCustomImageLabelerOptions alloc] initWithLocalModel:localModel];
}
options.confidenceThreshold = @(0.0);
MLKImageLabeler *imageLabeler =
    [MLKImageLabeler imageLabelerWithOptions:options];

اگر فقط یک مدل با میزبانی از راه دور دارید، باید عملکردهای مربوط به مدل را غیرفعال کنید - به عنوان مثال، خاکستری کردن یا پنهان کردن بخشی از رابط کاربری خود - تا زمانی که تأیید کنید مدل دانلود شده است.

می‌توانید با پیوست کردن ناظران به مرکز اطلاع رسانی پیش‌فرض، وضعیت دانلود مدل را دریافت کنید. مطمئن شوید که از یک مرجع ضعیف به self در بلوک ناظر استفاده کنید، زیرا دانلودها ممکن است مدتی طول بکشد، و شی مبدا می‌تواند تا پایان دانلود آزاد شود. مثلا:

سریع

NotificationCenter.default.addObserver(
    forName: .mlkitModelDownloadDidSucceed,
    object: nil,
    queue: nil
) { [weak self] notification in
    guard let strongSelf = self,
        let userInfo = notification.userInfo,
        let model = userInfo[ModelDownloadUserInfoKey.remoteModel.rawValue]
            as? RemoteModel,
        model.name == "your_remote_model"
        else { return }
    // The model was downloaded and is available on the device
}

NotificationCenter.default.addObserver(
    forName: .mlkitModelDownloadDidFail,
    object: nil,
    queue: nil
) { [weak self] notification in
    guard let strongSelf = self,
        let userInfo = notification.userInfo,
        let model = userInfo[ModelDownloadUserInfoKey.remoteModel.rawValue]
            as? RemoteModel
        else { return }
    let error = userInfo[ModelDownloadUserInfoKey.error.rawValue]
    // ...
}

هدف-C

__weak typeof(self) weakSelf = self;

[NSNotificationCenter.defaultCenter
    addObserverForName:MLKModelDownloadDidSucceedNotification
                object:nil
                 queue:nil
            usingBlock:^(NSNotification *_Nonnull note) {
              if (weakSelf == nil | note.userInfo == nil) {
                return;
              }
              __strong typeof(self) strongSelf = weakSelf;

              MLKRemoteModel *model = note.userInfo[MLKModelDownloadUserInfoKeyRemoteModel];
              if ([model.name isEqualToString:@"your_remote_model"]) {
                // The model was downloaded and is available on the device
              }
            }];

[NSNotificationCenter.defaultCenter
    addObserverForName:MLKModelDownloadDidFailNotification
                object:nil
                 queue:nil
            usingBlock:^(NSNotification *_Nonnull note) {
              if (weakSelf == nil | note.userInfo == nil) {
                return;
              }
              __strong typeof(self) strongSelf = weakSelf;

              NSError *error = note.userInfo[MLKModelDownloadUserInfoKeyError];
            }];

2. تصویر ورودی را آماده کنید

با استفاده از UIImage یا CMSampleBuffer یک شی VisionImage ایجاد کنید.

اگر از UIImage استفاده می کنید، این مراحل را دنبال کنید:

• با UIImage یک شی VisionImage ایجاد کنید. مطمئن شوید که جهت .orientation را مشخص کرده اید.

  سریع

  let image = VisionImage(image: UIImage)
  visionImage.orientation = image.imageOrientation

  هدف-C

  MLKVisionImage *visionImage = [[MLKVisionImage alloc] initWithImage:image];
  visionImage.orientation = image.imageOrientation;

اگر از CMSampleBuffer استفاده می کنید، این مراحل را دنبال کنید:

• جهت داده های تصویر موجود در CMSampleBuffer را مشخص کنید.

  برای دریافت جهت تصویر:

  سریع

  func imageOrientation(
    deviceOrientation: UIDeviceOrientation,
    cameraPosition: AVCaptureDevice.Position
  ) -> UIImage.Orientation {
    switch deviceOrientation {
    case .portrait:
      return cameraPosition == .front ? .leftMirrored : .right
    case .landscapeLeft:
      return cameraPosition == .front ? .downMirrored : .up
    case .portraitUpsideDown:
      return cameraPosition == .front ? .rightMirrored : .left
    case .landscapeRight:
      return cameraPosition == .front ? .upMirrored : .down
    case .faceDown, .faceUp, .unknown:
      return .up
    }
  }
        

  هدف-C

  - (UIImageOrientation)
    imageOrientationFromDeviceOrientation:(UIDeviceOrientation)deviceOrientation
                           cameraPosition:(AVCaptureDevicePosition)cameraPosition {
    switch (deviceOrientation) {
      case UIDeviceOrientationPortrait:
        return cameraPosition == AVCaptureDevicePositionFront ? UIImageOrientationLeftMirrored
                                                              : UIImageOrientationRight;
  
      case UIDeviceOrientationLandscapeLeft:
        return cameraPosition == AVCaptureDevicePositionFront ? UIImageOrientationDownMirrored
                                                              : UIImageOrientationUp;
      case UIDeviceOrientationPortraitUpsideDown:
        return cameraPosition == AVCaptureDevicePositionFront ? UIImageOrientationRightMirrored
                                                              : UIImageOrientationLeft;
      case UIDeviceOrientationLandscapeRight:
        return cameraPosition == AVCaptureDevicePositionFront ? UIImageOrientationUpMirrored
                                                              : UIImageOrientationDown;
      case UIDeviceOrientationUnknown:
      case UIDeviceOrientationFaceUp:
      case UIDeviceOrientationFaceDown:
        return UIImageOrientationUp;
    }
  }
        

• یک شی VisionImage با استفاده از شی CMSampleBuffer و جهت گیری ایجاد کنید:

  سریع

  let image = VisionImage(buffer: sampleBuffer)
  image.orientation = imageOrientation(
    deviceOrientation: UIDevice.current.orientation,
    cameraPosition: cameraPosition)

  هدف-C

   MLKVisionImage *image = [[MLKVisionImage alloc] initWithBuffer:sampleBuffer];
   image.orientation =
     [self imageOrientationFromDeviceOrientation:UIDevice.currentDevice.orientation
                                  cameraPosition:cameraPosition];

3. برچسب تصویر را اجرا کنید

برای برچسب گذاری اشیاء در یک تصویر، شی image را به متد process() ImageLabeler ارسال کنید.

به صورت ناهمزمان:

سریع

imageLabeler.process(image) { labels, error in
    guard error == nil, let labels = labels, !labels.isEmpty else {
        // Handle the error.
        return
    }
    // Show results.
}

هدف-C

[imageLabeler
    processImage:image
      completion:^(NSArray *_Nullable labels,
                   NSError *_Nullable error) {
        if (label.count == 0) {
            // Handle the error.
            return;
        }
        // Show results.
     }];

به صورت همزمان:

سریع

var labels: [ImageLabel]
do {
    labels = try imageLabeler.results(in: image)
} catch let error {
    // Handle the error.
    return
}
// Show results.

هدف-C

NSError *error;
NSArray *labels =
    [imageLabeler resultsInImage:image error:&error];
// Show results or handle the error.

4. اطلاعاتی در مورد نهادهای دارای برچسب دریافت کنید

اگر عملیات برچسب‌گذاری تصویر با موفقیت انجام شود، آرایه‌ای از ImageLabel را برمی‌گرداند. هر ImageLabel چیزی را نشان می دهد که در تصویر برچسب گذاری شده است. می‌توانید توضیحات متنی هر برچسب (در صورت موجود بودن در فراداده فایل مدل TensorFlow Lite)، امتیاز اطمینان و فهرست را دریافت کنید. مثلا:

سریع

for label in labels {
  let labelText = label.text
  let confidence = label.confidence
  let index = label.index
}

هدف-C

for (MLKImageLabel *label in labels) {
  NSString *labelText = label.text;
  float confidence = label.confidence;
  NSInteger index = label.index;
}

نکاتی برای بهبود عملکرد در زمان واقعی

اگر می خواهید تصاویر را در یک برنامه بلادرنگ برچسب گذاری کنید، این دستورالعمل ها را دنبال کنید تا به بهترین نرخ فریم برسید:

• برای پردازش فریم‌های ویدئویی، از API همگام results(in:) آشکارساز استفاده کنید. این روش را از تابع captureOutput(_, didOutput:from:) AVCaptureVideoDataOutputSampleBufferDelegate فراخوانی کنید تا به طور همزمان نتایج را از فریم ویدیوی داده شده دریافت کنید. قاب‌های AVCaptureVideoDataOutput alwaysDiscardsLateVideoFrames برای کاهش تماس‌های آشکارساز true نگه دارید. اگر یک قاب ویدیویی جدید در حالی که آشکارساز در حال کار است در دسترس باشد، حذف خواهد شد.
• اگر از خروجی آشکارساز برای همپوشانی گرافیک روی تصویر ورودی استفاده می‌کنید، ابتدا نتیجه را از کیت ML بگیرید، سپس تصویر را در یک مرحله رندر کنید و همپوشانی کنید. با انجام این کار، برای هر فریم ورودی پردازش شده فقط یک بار به سطح نمایشگر رندر می دهید. به عنوان مثال به updatePreviewOverlayViewWithLastFrame در نمونه راه اندازی سریع ML Kit مراجعه کنید.