pyopenbr 0.2

Improved Python Wrapper for the OpenBR Command-line Tool.

pyopenbr

An alternative Python wrapper for OpenBR which uses the Command Line Tool.

Simple Usage:

import pyopenbr
result = pyopenbr.run(algorithm="FaceRecognition", compare="image1.jpg model.gal")
print(result)

Documentation:

Parameters:

The parameters and the algorithms are exactly the same as the OpenBR Command-Line tool. The official documentation can be found at: http://openbiometrics.org/docs/api_docs/cl_api/

Syntax:

These are valid syntax examples for doing the same thing:

# [1st Option] --> RECOMMENDED
result = pyopenbr.run("output.csv", algorithm="FaceRecognition", compare="image1.jpg model.gal")

# [2nd Option - Splitting the parameter-option pairs]
result = pyopenbr.run("output.csv", "-algorithm FaceRecognition", "-compare image1.jpg model.gal")

# [3rd Option - Copying the Command Line Tool's parameters as a second argument of the `run` function]
result = pyopenbr.run("output.csv", "-algorithm FaceRecognition -compare image1.jpg model.gal")

Notes:

• The output parameter is optional.

• The argument names for the 1st option are not hard-coded. This means that any argument is translated to the format whic the OpenBR tool uses.

• The command always returns the content of the output of the OpenBR tool. (even if it is an unreadable format - e.g. raw format)

• If the output parameter is omitted, or it ends in .csv, then the returned value will be a Dictionary with the result of the OpenBR tool.

Example - Face Recognition:

# You can read the official tutorial with the Command Line tool here: http://openbiometrics.org/docs/tutorials/#face-recognition
# and see the similarities in the usage.
import pyopenbr

# Train the model with images in the `train` directory and store it in `model.gal`:
pyopenbr.run("model.gal", "-enrollAll -enroll train/", algorithm="FaceRecognition")

# Run a test of the trained model:
result = pyopenbr.run(algorithm="FaceRecognition", compare="model.gal testImage.jpg")

Options to Configure:

You can configure two things in the module:

• Disable error printing in the Terminal: pyopenbr.disableErrors()

• Provide your Path for the OpenBR Command-Line tool: pyopenbr.setExecutable(path). By default, the module will try to find the executable in your system.

Requirements:

You need to have OpenBR installed on your system. For installation instructions please visit: http://openbiometrics.org/docs/install/

Compatibility:

The module is compatible with Windows, Mac OS X and *nix Systems. It has been tested under Mac OS X El Capitan. Both Python 2.7 and Python 3 are supported.

Advantages/Disadvantages:

Using this Wrapper has many advantages that the official Python wrapper doesn’t: - Solves many Memory Issues (e.g. when handling a lot of images), and it is simpler to use. - Won’t throw any Segmentation Faults or other C/C++ related errors, which are common in the official wrapper. - Doesn’t need special parameters when you run cmake in order to be installed. - Simple usage, because it is similar to the OpenBR Command Line tool. (Which is also the most well-documented in the OpenBR Website, including Tutorials).

However, there is one disadvantage: It is slower than the official python wrapper. The official wrapper doesn’t initialize/finalize the OpenBR object when used for many sequential processeses. This one, however, does. This is unavoidable since we essentially call the OpenBR command line tool.

Speed Test:

I did a quick experiment to see the time difference between the official Python wrapper and this module. The test was about recognizing a face of the same image, against a trained model:

• The official Wrapper timing: 0.182754993439

• Our timing: 0.663321971893

So, there is a huge difference between the speed performance of the two wrappers. Probably this is the trade-off between speed and stability.

Notice:

This is a rather simple wrapper which uses basic ways to communicate with the OpenBR executable. However, it is stable and easy to use, which is the reason why I publish it as open-source.

Contact:

You can contact me via e-mail at: antonis.katzourakis{AT}gmail{DOT}com

Twitter: @ant0nisktz

License:

Copyright 2016 Antonios Katzourakis

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.