🤖 AIによる機械翻訳（非公式） — これは OpenCV 4.13.0 公式リファレンス（英語）を AI (Claude) で自動翻訳したものです。訳に誤りを含む場合があります。正確な情報は 公式英語版（原文） を参照してください。
Package org.opencv.face

クラス FaceRecognizer

  • 既知の直接サブクラス:
    BasicFaceRecognizer, LBPHFaceRecognizer
    public class FaceRecognizer
extends Algorithm
    Abstract base class for all face recognition models All face recognition models in OpenCV are derived from the abstract base class FaceRecognizer, which provides a unified access to all face recongition algorithms in OpenCV. ### Description I'll go a bit more into detail explaining FaceRecognizer, because it doesn't look like a powerful interface at first sight. But: Every FaceRecognizer is an Algorithm, so you can easily get/set all model internals (if allowed by the implementation). Algorithm is a relatively new OpenCV concept, which is available since the 2.4 release. I suggest you take a look at its description. Algorithm provides the following features for all derived classes:
    • いわゆる「仮想コンストラクタ」。すなわち、各 Algorithm 派生クラスはプログラム開始時に登録され、登録済みアルゴリズムの一覧を取得したり、名前を指定して特定のアルゴリズムのインスタンスを生成したりできる (Algorithm::create を参照)。独自のアルゴリズムを追加する予定がある場合は、他のアルゴリズムと区別できるよう、自分のアルゴリズムに一意のプレフィックスを付けるのが良い習慣である。
    • アルゴリズムの引数を名前で設定・取得する。OpenCV の highgui モジュールの動画キャプチャ機能を使ったことがあれば、cv::cvSetCaptureProperty、ocvcvGetCaptureProperty、VideoCapture::set、VideoCapture::get におそらく馴染みがあるだろう。Algorithm はこれと同様のメソッドを提供するが、整数の id の代わりに引数名をテキストの String で指定する。詳細は Algorithm::set および Algorithm::get を参照。
    • XML または YAML ファイルから引数を読み書きする。すべての Algorithm 派生クラスは、自身のすべての引数を保存し、後でそれらを読み戻すことができる。これを毎回再実装する必要はない。
    Moreover every FaceRecognizer supports the:
    • 与えられた画像群 (あなたの顔データベース!) に対する、FaceRecognizer::train による FaceRecognizer の学習。
    • 与えられたサンプル画像、すなわち顔の予測。画像は Mat として与えられる。
    • 与えられたXMLまたはYAMLとの間でのモデル状態の読み込み/保存。
    • 文字列として保存されるラベル情報の設定/取得。文字列のラベル情報は、認識した人物の名前を保持するのに便利である。
    覚え書き: When using the FaceRecognizer interface in combination with Python, please stick to Python 2. Some underlying scripts like create_csv will not work in other versions, like Python 3. Setting the Thresholds +++++++++++++++++++++++ Sometimes you run into the situation, when you want to apply a threshold on the prediction. A common scenario in face recognition is to tell, whether a face belongs to the training dataset or if it is unknown. You might wonder, why there's no public API in FaceRecognizer to set the threshold for the prediction, but rest assured: It's supported. It just means there's no generic way in an abstract class to provide an interface for setting/getting the thresholds of *every possible* FaceRecognizer algorithm. The appropriate place to set the thresholds is in the constructor of the specific FaceRecognizer and since every FaceRecognizer is a Algorithm (see above), you can get/set the thresholds at runtime! Here is an example of setting a threshold for the Eigenfaces method, when creating the model: // Let's say we want to keep 10 Eigenfaces and have a threshold value of 10.0 int num_components = 10; double threshold = 10.0; // Then if you want to have a cv::FaceRecognizer with a confidence threshold, // create the concrete implementation with the appropriate parameters: Ptr<FaceRecognizer> model = EigenFaceRecognizer::create(num_components, threshold); Sometimes it's impossible to train the model, just to experiment with threshold values. Thanks to Algorithm it's possible to set internal model thresholds during runtime. Let's see how we would set/get the prediction for the Eigenface model, we've created above: // The following line reads the threshold from the Eigenfaces model: double current_threshold = model->getDouble("threshold"); // And this line sets the threshold to 0.0: model->set("threshold", 0.0); If you've set the threshold to 0.0 as we did above, then: // Mat img = imread("person1/3.jpg", IMREAD_GRAYSCALE); // Get a prediction from the model. Note: We've set a threshold of 0.0 above, // since the distance is almost always larger than 0.0, you'll get -1 as // label, which indicates, this face is unknown int predicted_label = model->predict(img); // ... is going to yield -1 as predicted label, which states this face is unknown. ### Getting the name of a FaceRecognizer Since every FaceRecognizer is a Algorithm, you can use Algorithm::name to get the name of a FaceRecognizer: // Create a FaceRecognizer: Ptr<FaceRecognizer> model = EigenFaceRecognizer::create(); // And here's how to get its name: String name = model->name();

    • フィールドの要約

    • コンストラクタの要約

      コンストラクタ
      Modifier Constructor Description
      protected FaceRecognizer​(long addr)  

    • メソッドの要約

      すべてのメソッド 静的メソッド インスタンスメソッド 具象メソッド
      Modifier and Type Method Description
      static FaceRecognizer __fromPtr__​(long addr)  
      java.lang.String getLabelInfo​(int label)
      Gets string information by label.
      MatOfInt getLabelsByString​(java.lang.String str)
      Gets vector of labels by string.
      void predict​(Mat src, int[] label, double[] confidence)
      Predicts a label and associated confidence (e.g.
      void predict_collect​(Mat src, PredictCollector collector)
      if implemented - send all result of prediction to collector that can be used for somehow custom result handling
      int predict_label​(Mat src)  
      void read​(java.lang.String filename)
      Loads a FaceRecognizer and its model state.
      void setLabelInfo​(int label, java.lang.String strInfo)
      Sets string info for the specified model's label.
      void train​(java.util.List<Mat> src, Mat labels)
      Trains a FaceRecognizer with given data and associated labels.
      void update​(java.util.List<Mat> src, Mat labels)
      Updates a FaceRecognizer with given data and associated labels.
      void write​(java.lang.String filename)
      Saves a FaceRecognizer and its model state.

      • クラス java.lang.Object から継承したメソッド

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • コンストラクタの詳細

      • FaceRecognizer

        protected FaceRecognizer​(long addr)

    • メソッドの詳細

      • __fromPtr__

        public static FaceRecognizer __fromPtr__​(long addr)

      • train

        public void train​(java.util.List<Mat> src,
                  Mat labels)
        Trains a FaceRecognizer with given data and associated labels.
        引数:
        src - 学習用画像、すなわち学習させたい顔。データは vector<Mat> として与える必要がある。
        labels - 画像に対応するラベル。vector<int> または CV_32SC1 型の Mat のいずれかで与える必要がある。以下のソースコードの抜粋は、与えられた画像群から Fisherfaces モデルを学習する方法を示している。画像は imread で読み込まれ、std::vector<Mat> に追加される。各画像のラベルは std::vector<int> に格納される (CV_32SC1 型の Mat を使うこともできる)。ラベルは、その画像が属する被写体 (人物) と考えればよい。したがって同じ被写体 (人物) は同じラベルを持つべきである。利用可能な FaceRecognizer では、ラベルの順序に注意を払う必要はなく、同じ人物が同じラベルを持つことだけを確認すればよい: // holds images and labels vector<Mat> images; vector<int> labels; // using Mat of type CV_32SC1 // Mat labels(number_of_samples, 1, CV_32SC1); // images for first person images.push_back(imread("person0/0.jpg", IMREAD_GRAYSCALE)); labels.push_back(0); images.push_back(imread("person0/1.jpg", IMREAD_GRAYSCALE)); labels.push_back(0); images.push_back(imread("person0/2.jpg", IMREAD_GRAYSCALE)); labels.push_back(0); // images for second person images.push_back(imread("person1/0.jpg", IMREAD_GRAYSCALE)); labels.push_back(1); images.push_back(imread("person1/1.jpg", IMREAD_GRAYSCALE)); labels.push_back(1); images.push_back(imread("person1/2.jpg", IMREAD_GRAYSCALE)); labels.push_back(1); いくつかの画像を読み込んだので、新しい FaceRecognizer を作成できる。この例では Fisherfaces モデルを作成し、可能なすべての Fisherfaces を保持することにする: // Create a new Fisherfaces model and retain all available Fisherfaces, // this is the most common usage of this specific FaceRecognizer: // Ptr<FaceRecognizer> model = FisherFaceRecognizer::create(); そして最後に、与えられたデータセット (顔画像とラベル) で学習する: // This is the common interface to train all of the available cv::FaceRecognizer // implementations: // model->train(images, labels);

      • update

        public void update​(java.util.List<Mat> src,
                   Mat labels)
        Updates a FaceRecognizer with given data and associated labels.
        引数:
        src - 学習用画像、すなわち学習させたい顔。データは vector<Mat> として与える必要がある。
        labels - 画像に対応するラベル。vector<int> または CV_32SC1 型の Mat のいずれかで与える必要がある。このメソッドは (おそらく学習済みの) FaceRecognizer を更新するが、それはアルゴリズムが対応している場合に限られる。Local Binary Patterns Histograms (LBPH) 認識器 (createLBPHFaceRecognizer を参照) は更新できる。Eigenfaces および Fisherfaces の手法では、これはアルゴリズム上不可能であり、FaceRecognizer::train でモデルを再推定する必要がある。いずれの場合も、train を呼び出すと既存のモデルは空になり新しいモデルを学習するのに対し、update はモデルデータを一切削除しない。 // Create a new LBPH model (it can be updated) and use the default parameters, // this is the most common usage of this specific FaceRecognizer: // Ptr<FaceRecognizer> model = LBPHFaceRecognizer::create(); // This is the common interface to train all of the available cv::FaceRecognizer // implementations: // model->train(images, labels); // Some containers to hold new image: vector<Mat> newImages; vector<int> newLabels; // You should add some images to the containers: // // ... // // Now updating the model is as easy as calling: model->update(newImages,newLabels); // This will preserve the old model data and extend the existing model // with the new features extracted from newImages! 更新に対応していない Eigenfaces モデル (EigenFaceRecognizer::create を参照) に対して update を呼び出すと、次のようなエラーがスローされる: OpenCV Error: The function/feature is not implemented (This FaceRecognizer (FaceRecognizer.Eigenfaces) does not support updating, you have to use FaceRecognizer::train to update it.) in update, file /home/philipp/git/opencv/modules/contrib/src/facerec.cpp, line 305 terminate called after throwing an instance of 'cv::Exception' 注: FaceRecognizer は学習用画像を保存しない。これは非常にメモリを消費するうえ、それを行うのは FaceRecognizer の責務ではないからである。データセットの管理は、それを扱おうとする呼び出し側の責任である。

      • predict_label

        public int predict_label​(Mat src)

      • predict

        public void predict​(Mat src,
                    int[] label,
                    double[] confidence)
        Predicts a label and associated confidence (e.g. distance) for a given input image.
        引数:
        src - 予測を得るためのサンプル画像。
        label - 与えられた画像に対して予測されたラベル。
        confidence - 予測されたラベルに付随する信頼度 (例: 距離)。接尾辞 const は、予測が内部のモデル状態に影響を与えないことを意味し、そのためこのメソッドは異なるスレッドから安全に呼び出せる。次の例は、学習済みモデルから予測を得る方法を示す: using namespace cv; // Do your initialization here (create the cv::FaceRecognizer model) ... // ... // Read in a sample image: Mat img = imread("person1/3.jpg", IMREAD_GRAYSCALE); // And get a prediction from the cv::FaceRecognizer: int predicted = model->predict(img); あるいは、予測と付随する信頼度 (例: 距離) を得るには: using namespace cv; // Do your initialization here (create the cv::FaceRecognizer model) ... // ... Mat img = imread("person1/3.jpg", IMREAD_GRAYSCALE); // Some variables for the predicted label and associated confidence (e.g. distance): int predicted_label = -1; double predicted_confidence = 0.0; // Get the prediction and associated confidence from the model model->predict(img, predicted_label, predicted_confidence);

      • predict_collect

        public void predict_collect​(Mat src,
                            PredictCollector collector)
        • 実装されている場合 - 予測のすべての結果を、独自の結果処理に利用できるコレクタに送る
        引数:
        src - 予測を得るためのサンプル画像。
        collector - すべての結果を受け取るユーザー定義のコレクタオブジェクト。このメソッドを実装するには、predict(InputArray src, CV_OUT int &label, CV_OUT double &confidence) と同じ内部ループを行えばよいが、「最良の」結果を得ようとせず、与えられたコレクタを介して呼び出し側にそのまま送り返す。

      • write

        public void write​(java.lang.String filename)
        Saves a FaceRecognizer and its model state. Saves this model to a given filename, either as XML or YAML.
        引数:
        filename - この FaceRecognizer を保存するファイル名 (XML/YAML のいずれか)。すべての FaceRecognizer は内部のモデル状態を保存するために FaceRecognizer::save(FileStorage& fs) をオーバーライドする。FaceRecognizer::save(const String& filename) はモデルの状態を与えられたファイル名に保存する。接尾辞 const は、予測が内部のモデル状態に影響を与えないことを意味し、そのためこのメソッドは異なるスレッドから安全に呼び出せる。

      • read

        public void read​(java.lang.String filename)
        Loads a FaceRecognizer and its model state. Loads a persisted model and state from a given XML or YAML file . Every FaceRecognizer has to overwrite FaceRecognizer::load(FileStorage& fs) to enable loading the model state. FaceRecognizer::load(FileStorage& fs) in turn gets called by FaceRecognizer::load(const String& filename), to ease saving a model.
        引数:
        filename - 自動生成

      • setLabelInfo

        public void setLabelInfo​(int label,
                         java.lang.String strInfo)
        Sets string info for the specified model's label. The string info is replaced by the provided value if it was set before for the specified label.
        引数:
        label - 自動生成
        strInfo - 自動生成

      • getLabelInfo

        public java.lang.String getLabelInfo​(int label)
        Gets string information by label. If an unknown label id is provided or there is no label information associated with the specified label id the method returns an empty string.
        引数:
        label - 自動生成
        戻り値:
        自動生成

      • getLabelsByString

        public MatOfInt getLabelsByString​(java.lang.String str)
        Gets vector of labels by string. The function searches for the labels containing the specified sub-string in the associated string info.
        引数:
        str - 自動生成
        戻り値:
        自動生成