Merge pull request #696 from khanhlvg:image-classifier-c-api

PiperOrigin-RevId: 398347514

Author: tflite-support-robot

tensorflow_lite_support/c/task/processor/classification_options.h

@@ -34,17 +34,16 @@ typedef struct TfLiteStringArrayOption {
 } TfLiteStringArrayOption;
 
 // Holds settings for any single classification task.
-// TODO(prianka): change `white/blacklist` to `allow/denylist`
 typedef struct TfLiteClassificationOptions {
-  // Optional blacklist of class names. If non NULL, classifications whose
-  // class name is in this set will be filtered out. Duplicate or unknown
-  // class names are ignored. Mutually exclusive with class_name_whitelist.
-  TfLiteStringArrayOption class_name_blacklist;
-
-  // Optional whitelist of class names. If non-empty, classifications whose
-  // class name is not in this set will be filtered out. Duplicate or unknown
-  // class names are ignored. Mutually exclusive with class_name_blacklist.
-  TfLiteStringArrayOption class_name_whitelist;
+  // Optional denylist of class labels. If non NULL, classifications whose
+  // class label is in this set will be filtered out. Duplicate or unknown
+  // class labels are ignored. Mutually exclusive with label_allowlist.
+  TfLiteStringArrayOption label_denylist;
+
+  // Optional allowlist of class labels. If non-empty, classifications whose
+  // class label is not in this set will be filtered out. Duplicate or unknown
+  // class labels are ignored. Mutually exclusive with label_denylist.
+  TfLiteStringArrayOption label_allowlist;
 
   const char* display_names_local;
   int max_results;

tensorflow_lite_support/c/task/vision/image_classifier.cc

@@ -42,6 +42,12 @@ struct TfLiteImageClassifier {
   std::unique_ptr<ImageClassifierCpp> impl;
 };
 
+TfLiteImageClassifierOptions TfLiteImageClassifierOptionsCreate() {
+  return {.classification_options = {.max_results = -1},
+          .base_options = {
+              .compute_settings = {.cpu_settings = {.num_threads = -1}}}};
+}
+
 std::unique_ptr<ImageClassifierOptionsCpp>
 CreateImageClassifierCppOptionsFromCOptions(
     const TfLiteImageClassifierOptions* c_options) {
@@ -55,28 +61,25 @@ CreateImageClassifierCppOptionsFromCOptions(
   else
     return nullptr;
 
-  // Without this check, in zero initialized TfLiteImageClassifierOptions (must
-  // be done to prevent undefined behaviour)
-  // c_options->base_options.compute_settings.num_threads should be explicitly
+  // c_options->base_options.compute_settings.num_threads is expected to be
   // set to value > 0 or -1. Otherwise invoking
   // ImageClassifierCpp::CreateFromOptions() results in a not ok status.
-  if (c_options->base_options.compute_settings.cpu_settings.num_threads > 0)
-    cpp_options->mutable_base_options()
-        ->mutable_compute_settings()
-        ->mutable_tflite_settings()
-        ->mutable_cpu_settings()
-        ->set_num_threads(
-            c_options->base_options.compute_settings.cpu_settings.num_threads);
-
-  for (int i = 0;
-       i < c_options->classification_options.class_name_blacklist.length; i++)
+  cpp_options->mutable_base_options()
+      ->mutable_compute_settings()
+      ->mutable_tflite_settings()
+      ->mutable_cpu_settings()
+      ->set_num_threads(
+          c_options->base_options.compute_settings.cpu_settings.num_threads);
+
+  for (int i = 0; i < c_options->classification_options.label_denylist.length;
+       i++)
     cpp_options->add_class_name_blacklist(
-        c_options->classification_options.class_name_blacklist.list[i]);
+        c_options->classification_options.label_denylist.list[i]);
 
-  for (int i = 0;
-       i < c_options->classification_options.class_name_whitelist.length; i++)
+  for (int i = 0; i < c_options->classification_options.label_allowlist.length;
+       i++)
     cpp_options->add_class_name_whitelist(
-        c_options->classification_options.class_name_whitelist.list[i]);
+        c_options->classification_options.label_allowlist.list[i]);
 
   // Check needed since setting a nullptr for this field results in a segfault
   // on invocation of ImageClassifierCpp::CreateFromOptions().
@@ -85,13 +88,10 @@ CreateImageClassifierCppOptionsFromCOptions(
         c_options->classification_options.display_names_local);
   }
 
-  // Without this check, in zero initialized TfLiteImageClassifierOptions (must
-  // be done to prevent undefined behaviour)
-  // c_options->classification_options.max_results should be explicitly set to
-  // value > 0. Otherwise invocation of ImageClassifierCpp::CreateFromOptions()
-  // will return a not ok status.
-  if (c_options->classification_options.max_results > 0)
-    cpp_options->set_max_results(c_options->classification_options.max_results);
+  // c_options->classification_options.max_results is expected to be set to -1
+  // or any value > 0. Otherwise invoking
+  // ImageClassifierCpp::CreateFromOptions() results in a not ok status.
+  cpp_options->set_max_results(c_options->classification_options.max_results);
 
   cpp_options->set_score_threshold(
       c_options->classification_options.score_threshold);

tensorflow_lite_support/c/task/vision/image_classifier.h

@@ -35,11 +35,19 @@ limitations under the License.
 /// Usage with Model File Path:
 /// <pre><code>
 /// // Create the model
-/// Zero initialize options to avoid undefined behaviour due to garbage values
-/// for members
-/// TfLiteImageClassifierOptions options = {0};
+/// Using the options initialized with default values returned by
+/// TfLiteImageClassifierOptionsCreate() makes sure that there will be no
+/// undefined behaviour due to garbage values in unitialized members.
+/// TfLiteImageClassifierOptions options = TfLiteImageClassifierOptionsCreate();
+///
+/// Set the model file path in options
 ///   options.base_options.model_file.file_path = "/path/to/model.tflite";
-///   TfLiteImageClassifier* image_classifier =
+///
+/// If need be, set values for any options to customize behaviour.
+/// options.base_options.compute_settings.cpu_settings.num_threads = 3
+///
+/// Create TfLiteImageClassifier using the options.
+/// TfLiteImageClassifier* image_classifier =
 ///       TfLiteImageClassifierFromOptions(&options);
 ///
 /// Classify an image
@@ -62,26 +70,37 @@ typedef struct TfLiteImageClassifierOptions {
   TfLiteBaseOptions base_options;
 } TfLiteImageClassifierOptions;
 
+// Creates and returns TfLiteImageClassifierOptions initialized with default
+// values. Default values are as follows:
+// 1. .classification_options.max_results = -1, which returns all classification
+// categories by default.
+// 2. .base_options.compute_settings.tflite_settings.cpu_settings.num_threads =
+// -1, which makes the TFLite runtime choose the value.
+// 3. .classification_options.score_threshold = 0
+// 4. All pointers like .base_options.model_file.file_path,
+// .base_options.classification_options.display_names_local,
+// .classification_options.label_allowlist.list,
+// options.classification_options.label_denylist.list are NULL.
+// 5. All other integer values are initialized to 0.
+TfLiteImageClassifierOptions TfLiteImageClassifierOptionsCreate();
+
 // Creates TfLiteImageClassifier from options.
-// base_options.model_file.file_path in TfLiteImageClassifierOptions should be
+// .base_options.model_file.file_path in TfLiteImageClassifierOptions should be
 // set to the path of the tflite model you wish to create the
 // TfLiteImageClassifier with.
 // Returns nullptr under the following circumstances:
 // 1. file doesn't exist or is not a well formatted.
 // 2. options is nullptr.
-// 3. Both options.classification_options.class_name_blacklist and
-// options.classification_options.class_name_blacklist are non empty. These
+// 3. Both options.classification_options.label_denylist and
+// options.classification_options.label_allowlist are non empty. These
 // fields are mutually exclusive.
 //
-// If
-// options->base_options.compute_settings.tflite_settings.cpu_settings.num_threads
-// <= 0, it will be set to a default of -1 which indicates the TFLite runtime to
-// choose the value.
-//
-// TfLiteImageClassifierOptions must be zero initialized to avoid seg faults.
-//
-// TODO(prianka): create default TfLiteImageClassifierOptions with default
-// values.
+// Create TfLiteImageClassifierOptions using
+// TfLiteImageClassifierOptionsCreate(). If need be, you can change the default
+// values of options for customizing classification, If options are not created
+// in the aforementioned way, you have to make sure that all members are
+// initialized to respective default values and all pointer members are zero
+// initialized to avoid any undefined behaviour.
 TfLiteImageClassifier* TfLiteImageClassifierFromOptions(
     const TfLiteImageClassifierOptions* options);
 

tensorflow_lite_support/c/test/task/vision/image_classifier_test.cc

@@ -48,7 +48,7 @@ StatusOr<ImageData> LoadImage(const char* image_name) {
 class ImageClassifierFromOptionsTest : public tflite_shims::testing::Test {};
 
 TEST_F(ImageClassifierFromOptionsTest, FailsWithMissingModelPath) {
-  TfLiteImageClassifierOptions options = {{{0}}};
+  TfLiteImageClassifierOptions options = TfLiteImageClassifierOptionsCreate();
   TfLiteImageClassifier* image_classifier =
       TfLiteImageClassifierFromOptions(&options);
   EXPECT_EQ(image_classifier, nullptr);
@@ -58,7 +58,7 @@ TEST_F(ImageClassifierFromOptionsTest, SucceedsWithModelPath) {
   std::string model_path =
       JoinPath("./" /*test src dir*/, kTestDataDirectory,
                kMobileNetQuantizedWithMetadata);
-  TfLiteImageClassifierOptions options = {{{0}}};
+  TfLiteImageClassifierOptions options = TfLiteImageClassifierOptionsCreate();
   options.base_options.model_file.file_path = model_path.data();
   TfLiteImageClassifier* image_classifier =
       TfLiteImageClassifierFromOptions(&options);
@@ -71,7 +71,7 @@ TEST_F(ImageClassifierFromOptionsTest, SucceedsWithNumberOfThreads) {
   std::string model_path =
       JoinPath("./" /*test src dir*/, kTestDataDirectory,
                kMobileNetQuantizedWithMetadata);
-  TfLiteImageClassifierOptions options = {{{0}}};
+  TfLiteImageClassifierOptions options = TfLiteImageClassifierOptionsCreate();
   options.base_options.model_file.file_path = model_path.data();
   options.base_options.compute_settings.cpu_settings.num_threads = 3;
   TfLiteImageClassifier* image_classifier =
@@ -82,23 +82,21 @@ TEST_F(ImageClassifierFromOptionsTest, SucceedsWithNumberOfThreads) {
 }
 
 TEST_F(ImageClassifierFromOptionsTest,
-       FailsWithClassNameBlackListAndClassNameWhiteList) {
+       FailsWithClassNameDenyListAndClassNameAllowList) {
   std::string model_path =
       JoinPath("./" /*test src dir*/, kTestDataDirectory,
                kMobileNetQuantizedWithMetadata);
 
-  TfLiteImageClassifierOptions options = {{{0}}};
+  TfLiteImageClassifierOptions options = TfLiteImageClassifierOptionsCreate();
   options.base_options.model_file.file_path = model_path.data();
 
-  const char* class_name_blacklist[] = {"brambling"};
-  options.classification_options.class_name_blacklist.list =
-      class_name_blacklist;
-  options.classification_options.class_name_blacklist.length = 1;
+  const char* label_denylist[] = {"brambling"};
+  options.classification_options.label_denylist.list = label_denylist;
+  options.classification_options.label_denylist.length = 1;
 
-  const char* class_name_whitelist[] = {"cheeseburger"};
-  options.classification_options.class_name_whitelist.list =
-      class_name_whitelist;
-  options.classification_options.class_name_whitelist.length = 1;
+  const char* label_allowlist[] = {"cheeseburger"};
+  options.classification_options.label_allowlist.list = label_allowlist;
+  options.classification_options.label_allowlist.length = 1;
 
   TfLiteImageClassifier* image_classifier =
       TfLiteImageClassifierFromOptions(&options);
@@ -114,7 +112,7 @@ class ImageClassifierClassifyTest : public tflite_shims::testing::Test {
         JoinPath("./" /*test src dir*/, kTestDataDirectory,
                  kMobileNetQuantizedWithMetadata);
 
-    TfLiteImageClassifierOptions options = {{{0}}};
+    TfLiteImageClassifierOptions options = TfLiteImageClassifierOptionsCreate();
     options.base_options.model_file.file_path = model_path.data();
     image_classifier = TfLiteImageClassifierFromOptions(&options);
 
@@ -197,19 +195,18 @@ TEST_F(ImageClassifierClassifyTest, FailsWithRoiOutsideImageBounds) {
 }
 
 TEST(ImageClassifierWithUserDefinedOptionsClassifyTest,
-     SucceedsWithClassNameBlackList) {
-  const char* blacklisted_label_name = "cheeseburger";
+     SucceedsWithClassNameDenyList) {
+  const char* denylisted_label_name = "cheeseburger";
   std::string model_path =
       JoinPath("./" /*test src dir*/, kTestDataDirectory,
                kMobileNetQuantizedWithMetadata);
 
-  TfLiteImageClassifierOptions options = {{{0}}};
+  TfLiteImageClassifierOptions options = TfLiteImageClassifierOptionsCreate();
   options.base_options.model_file.file_path = model_path.data();
 
-  const char* class_name_blacklist[] = {blacklisted_label_name};
-  options.classification_options.class_name_blacklist.list =
-      class_name_blacklist;
-  options.classification_options.class_name_blacklist.length = 1;
+  const char* label_denylist[] = {denylisted_label_name};
+  options.classification_options.label_denylist.list = label_denylist;
+  options.classification_options.label_denylist.length = 1;
 
   TfLiteImageClassifier* image_classifier =
       TfLiteImageClassifierFromOptions(&options);
@@ -233,7 +230,7 @@ TEST(ImageClassifierWithUserDefinedOptionsClassifyTest,
   EXPECT_GE(classification_result->classifications->size, 1);
   EXPECT_NE(classification_result->classifications->categories, nullptr);
   EXPECT_NE(strcmp(classification_result->classifications->categories[0].label,
-                   blacklisted_label_name),
+                   denylisted_label_name),
             0);
 
   if (image_classifier) TfLiteImageClassifierDelete(image_classifier);
@@ -242,20 +239,19 @@ TEST(ImageClassifierWithUserDefinedOptionsClassifyTest,
 }
 
 TEST(ImageClassifierWithUserDefinedOptionsClassifyTest,
-     SucceedsWithClassNameWhiteList) {
-  const char* whitelisted_label_name = "cheeseburger";
+     SucceedsWithClassNameAllowList) {
+  const char* allowlisted_label_name = "cheeseburger";
   std::string model_path =
       JoinPath("./" /*test src dir*/, kTestDataDirectory,
                kMobileNetQuantizedWithMetadata)
           .data();
 
-  TfLiteImageClassifierOptions options = {{{0}}};
+  TfLiteImageClassifierOptions options = TfLiteImageClassifierOptionsCreate();
   options.base_options.model_file.file_path = model_path.data();
 
-  const char* class_name_whitelist[] = {whitelisted_label_name};
-  options.classification_options.class_name_whitelist.list =
-      class_name_whitelist;
-  options.classification_options.class_name_whitelist.length = 1;
+  const char* label_allowlist[] = {allowlisted_label_name};
+  options.classification_options.label_allowlist.list = label_allowlist;
+  options.classification_options.label_allowlist.length = 1;
 
   TfLiteImageClassifier* image_classifier =
       TfLiteImageClassifierFromOptions(&options);
@@ -279,7 +275,7 @@ TEST(ImageClassifierWithUserDefinedOptionsClassifyTest,
   EXPECT_GE(classification_result->classifications->size, 1);
   EXPECT_NE(classification_result->classifications->categories, nullptr);
   EXPECT_EQ(strcmp(classification_result->classifications->categories[0].label,
-                   whitelisted_label_name),
+                   allowlisted_label_name),
             0);
 
   if (image_classifier) TfLiteImageClassifierDelete(image_classifier);