To build OFIQ you need to install Python with pip, cmake and conan.
- Python (version 3.10.12 or higher)
- [Download and install cmake](https://cmake.org/) (version 3.26 or higher)
- [Download and install conan](https://conan.io/) (version 2.0.17)
Install necessary packages.
$ sudo apt-get install build-essential python3-pip
To install cmake (in a version 3.26 or higher) use snap (and not apt) as follows.
$ sudo snap install cmake --classic
Conan is installed via Python with
pip install conan==2.0.17
In order to build OFIQ and installing all required packages via conan run the following.
$ cd /path/to/OFIQ_Project/scripts $ sh build.sh
where /path/to/OFIQ_Project/ denotes the root folder of the OFIQ source files.
This will create the following output.
| file/directory | description |
| build/ | Folder with the Linux build including the binaries OFIQSampleApp and libofiq_lib.so. |
| build/conan/ | Conan cache with packages downloaded. |
| install_x86_64_linux/ | Folder with the installation including the binaries Release/bin/OFIQSampleApp,
Release/lib/libofiq_lib.so, Release/lib/libonnxruntime.so.1.17.3, and the
header files in Release/include/. |
| data/models/ | Model files downloaded from the ISO portal during build process. |
| data/tests/images/ | Conformance test images downloaded from the ISO portal. |
Install necessary packages.
$ sudo apt-get install build-essential python3-pip cmake python3.12-venv
To install conan, a virtual Python environment needs to be generated first.
$ python3 -m venv /path/to/py_ofiq_env
where /path/to/py_ofiq_env is the path where the python environment will be stored
and py_ofiq_env is the name of the new environment.
Then install conan as follows.
$ source /path/to/py_ofiq_env/bin/activate $ pip install conan==2.0.17
In order to build OFIQ and installing all required packages via conan run the following.
$ source /path/to/py_ofiq_env/bin/activate $ cd /path/to/OFIQ_Project/scripts $ sh build.sh
where /path/to/OFIQ_Project/ denotes the root folder of the OFIQ source files.
This will create the following output.
| file/directory | description |
| build/ | Folder with the Linux build including the binaries OFIQSampleApp and libofiq_lib.so. |
| build/conan/ | Conan cache with packages downloaded. |
| install_x86_64_linux/ | Folder with the installation including the binaries Release/bin/OFIQSampleApp,
Release/lib/libofiq_lib.so, Release/lib/libonnxruntime.so.1.17.3, and the
header files in Release/include/. |
| data/models/ | Model files downloaded from the ISO portal during build process. |
| data/tests/images/ | Conformance test images downloaded from the ISO portal. |
The following has been tested on a Windows 10 (64 bit) installation using a Python installation version 3.11.5
with pip package such that the pip command can be executed from the command prompt. Furthermore, an installation
of cmake version 3.29 has been used. As the compiler, Microsoft's Visual Studio 2019 was used.
To install conan, run
$ pip install conan==2.0.17
from the command prompt.
In order to build OFIQ and install all required packages run the following.
$ cd C:\\Path\To\OFIQ_Project\\scripts\\ $ .\build.cmd
where C:\Path\To\OFIQ_Project\ denotes the root folder of the OFIQ source files.
This will create the following output.
| file/directory | description |
| build\\build_win\\ | Folder with the Visual Studio solution files placed and pre-compilation. |
| build\\conan\\ | Conan cache with packages downloaded. |
| install_x86_64\\ | Folder with the OFIQ installation files. This includes the binaries Release\\bin\\OFIQSampleApp,
Release\\bin\\libofiq_lib.so, Release\\bin\\libonnxruntime.so.1.17.3, and the
header files in Release\\include\\. |
| data\\models\\ | Model files downloaded from the ISO portal during build process. |
| data\\tests\\images\\ | Conformance test images downloaded from the ISO portal. |
The following has been tested on macOS Sonoma Version 14.4.1 with ARM64 processor.
Install Homebrew
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Then update profiles
$ (echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> ~/.zprofile $ eval "$(/opt/homebrew/bin/brew shellenv)"
where /opt/homebrew/bin/brew is the path to the homebrew executable and can vary among MacOS systems.
NOTE The two commands from above for updating profiles are output by the Homebrew installation script.
Install CMake.
$ brew install cmake
Install Python using Miniconda by
$ mkdir -p /path/to/miniconda3/ $ curl https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh -o /path/to/miniconda3/miniconda.sh $ bash /path/to/miniconda3/miniconda.sh -b -u -p /path/to/miniconda3 $ rm -rf /path/to/miniconda3/miniconda.sh $ /path/to/miniconda3/bin/conda init bash $ /path/to/miniconda3/bin/conda init zsh
where /path/to/miniconda3 can be replaced by the path where Miniconda is installed.
Install conan.
$ python -m pip install conan==2.0.17
Finally, to build OFIQ run the following.
$ cd /path/to/OFIQ_Project/scripts/ $ sh build.sh --os macos
To compile OFIQ on MacOS x86_64 one needs to
edit /path/to/OFIQ_Project/conan/conan_profile_release_macos.txt
and /path/to/OFIQ_Project/conan/conan_profile_debug_macos.txt first. In both files replace the line
arch=armv8
by
arch=x86_64
Then apply the same actions as for MacOS compilation on ARM64.
To run OFIQ, the model files from the ISO portal
need to be downloaded and be placed in the ./data/models/ directory.
This step is integrated in the cmake building process.
To run conformance tests, the conformance test
images need to be downloaded from
the ISO portal
and be placed in the ./data/tests/images/ directory.
This step is integrated in the cmake building process.
The conformance tests are executed by going to /path/to/OFIQ_Project/scripts/
and run
conformance_tests.cmd(Windows).conformance_tests.sh(Linux).conformance_tests.sh --os(MacOS).
In this section, we describe how to run the sample application of OFIQ after compilation (see @ref sec_compilation). A documentation for the arguments that can be passed can be found @ref sec_sample_args "below".
The sample application takes an images and outputs the computed
quality assessments. For example, to output the quality
assessments for one of the conformance test images using OFIQ's configuration (in
./data), run the following commands on Linux.
$ cd /install_x86_64_linux/Release/bin/
$ ./OFIQSampleApp -c ../../../data/ofiq_config.jaxn -i
../../../data/tests/images/b-01-smile.png
On Windows run the following commands.
$ cd \\install_x86_64\\Release\\bin
$ .\OFIQSampleApp -c ..\\..\\..\\data\\ofiq_config.jaxn -i
..\\..\\..\\data\\tests\\images\\b-01-smile.png
To reproduce the conformance test table given in Annex A of the ISO/IEC 29794-5 international standard for all conformance test images, run the following commands on Linux.
$ cd /path/to/OFIQ_Project/install_x86_64_linux/Release/bin/
$ ./OFIQSampleApp -c ../../../data/ofiq_config.jaxn -i
../../../data/tests/images/ -o table.csv
The result will be written in the file
/path/to/OFIQ_Project/install_x86_64_linux/Release/bin/table.csv.
On Windows run the following commands.
$ cd C:\\Path\\To\\OFIQ_Project\\install_x86_64\\Release\\bin\\
$ .\\OFIQSampleApp -c ..\\..\\..\\data\\ -i
..\\..\\..\\data\\tests\\images\\ -o table.csv
The result will be written in the file
C:\Path\To\OFIQ_Project\install_x86_64\Release\bin\table.csv.
The usage pattern of the sample application is the following.
OFIQSampleApp
-c
[-cf ]
-i
[-o ]
The following table documents the usage of the sample application.
| flag | argument |
| -c | Path to a directory containing the file ofiq_config.jaxn or a path to a JAXN configuration file (see [doc/refman.pdf](doc/refman.pdf)). |
| -cf | Name of the JAXN configuration file contained in the directory specified by the flag -c. Must be omitted if -c specifies a path to a file. |
| -i | Path to a directory containing facial images or a path to a facial image file. If a directory path is specified, all images in PNG and JPEG format will be processed. |
| -o | Path to a CSV file to where the quality assessment is written. If -o is not specified, the output is written to the standard output. |