fiqat package

Submodules

fiqat.config module

This module handles configuration data loaded from a single .toml file. This configuration file is required to specify local dependency paths (e.g. to model files) for various methods that are included in the toolkit.

fiqat.config.config_path_loaded: Path = None

The config file path corresponding to the loaded config_data.

fiqat.config.config_data: dict = None

The loaded config data

fiqat.config.get_config_path_default()

Returns the default config file path (<fiqat_package_directory>/local/fiqat.toml).

fiqat.config.load_config_data(config_path: Path | None = None) → dict

Loads or reloads the config data and returns it.

Parameters:

config_path (Optional[Path]) – The path to the .toml config file. If this is None, the last loaded path will be used (config_path_loaded). If there is no last loaded path, the path specified via the environment variable 'FIQAT_CONFIG' is used (os.environ['FIQAT_CONFIG']). If that environment variable doesn’t exist, then the default path is used (get_config_path_default()).

Returns:

The loaded config data, which will also set the global fiqat.config.config_data.

Return type:

dict

fiqat.config.get_config_data()

Returns the loaded config data (fiqat.config.config_data). If it hasn’t been loaded yet, load_config_data() will be called first.

fiqat.draw module

Drawing utility functionality.

fiqat.draw.draw_face_detector_output(input_image: Path | ndarray | Image, face_detector_output: FaceDetectorOutput, resize_to: ImageSize | None = None, draw_landmarks: bool = True, draw_roi: bool = True, draw_confidence: bool = False, draw_face_labels: bool = False, draw_landmark_labels: bool = False, landmark_names: list[str] | None = None, method_registry_entry: FdMethodRegistryEntry | None = None, always_show_landmark_indices: bool = True, roi_color: Cv2ColorTuple = (0, 0, 255), roi_thickness: int = 2, landmark_color: Cv2ColorTuple = (0, 0, 255), landmark_thickness: int = 2, landmark_radius: int = 1, font_name: str | None = None, font_color: Cv2ColorTuple = (0, 0, 255), font_scale: float = 1, landmark_font_scale: float | None = None, primary_face_index: int | None = None, primary_face_color: Cv2ColorTuple = (0, 255, 0)) → TypedNpImage

Draws fiqat.types.FaceDetectorOutput data, e.g. facial landmarks, onto a copy of the given image.

Parameters:

  • input_image (InputImage) – The input image. The function internally uses cv2 for drawing. If a fiqat.types.TypedNpImage is passed a copy will be converted to fiqat.types.ImageChannelType.BGR if necessary. If an fiqat.types.NpImage is passed it is assumed to be of fiqat.types.ImageChannelType.BGR.

  • face_detector_output (FaceDetectorOutput) – The face detector output that includes the detected faces with the data that should be drawn.

  • resize_to (Optional[ImageSize]) – If set, the input image is resized to this size before drawing, using cv2.resize. The face_detector_output coordinates will be adjusted automatically. You can alternatively resize the image yourself prior to calling this function, since the coordinates will also be adjusted if the fiqat.types.FaceDetectorOutput.input_image_size deviates from the image’s size.

  • draw_landmarks (bool) – If True, the landmarks will be drawn. The drawing function is cv2.circle.

  • draw_roi (bool) – If True, the detected face ROI i.e. box will be drawn (if available in the face_detector_output data). The drawing function is cv2.rectangle.

  • draw_confidence (bool) – If True, the detector’s confidence value will be drawn (if available in the face_detector_output data). The confidence value will be shown with two digits after the decimal point. The drawing function is cv2.putText. This currently only works if ROI data is available to determine the text position.

  • draw_face_labels (bool) – If True, faces are labeled as “Face i”, i being the index starting at 1. The drawing function is cv2.putText. This currently only works if ROI data is available to determine the text position.

  • draw_landmark_labels (bool) – If True, the landmarks will be labeled. If specified, the landmark_names will be used as labels. Otherwise, if specified, method_registry_entry’s landmark_names will be used. If no landmark name is available at a landmark index, the indices starting at 1 will be used as labels. The drawing function is cv2.putText.

  • landmark_names (Optional[list[str]]) – If specified, these names will be used to label the drawn landmarks. Setting this has no effect if draw_landmark_labels is False.

  • method_registry_entry (Optional[FdMethodRegistryEntry]) – If specified, the fiqat.types.FdMethodRegistryEntry.landmark_names will be used to label the drawn landmarks. Setting this has no effect if landmark_names is set or if draw_landmark_labels is False.

  • always_show_landmark_indices (bool) – If landmark labels are drawn and if landmark names are provided, show the indices (starting at 1) as a prefix to the names.

  • roi_color (Cv2ColorTuple) – The color used to draw the face ROI rectangles.

  • roi_thickness (int) – The line thickness used to draw the face ROI rectangles.

  • landmark_color (Cv2ColorTuple) – The color used to draw the landmark dots.

  • landmark_thickness (int) – The line thickness used to draw the landmark dots.

  • landmark_radius (int) – The circle radius used to draw the landmark dots.

  • font_name (Optional[str]) – Name of the font that should be used to draw the labels.

  • font_color (Cv2ColorTuple) – Color of the font that should be used to draw the labels.

  • font_scale (float) – Scale of the font that should be used to draw the labels.

  • landmark_font_scale (Optional[float]) – Scale of the font that should be used to draw the landmark labels. If None, the font_scale will be used.

  • primary_face_index (Optional[int]) – Optional index of a “primary” detected face, which will be highlighted in the primary_face_color.

  • primary_face_color (Cv2ColorTuple) – This color will be used for the face with the primary_face_index for all drawing operations.

Returns:

The new image with drawn landmarks, with fiqat.types.ImageChannelType.BGR.

Return type:

fiqat.types.TypedNpImage

fiqat.edc module

“Error versus Discard Characteristic” (EDC) functionality. See e.g. “Considerations on the Evaluation of Biometric Quality Assessment Algorithms”.

class fiqat.edc.EdcSample

Bases: TypedDict

The input data for one sample that is required to compute an EDC curve, which is just the sample’s fiqat.types.QualityScore.

quality_score: float

The sample’s fiqat.types.QualityScore. In context of the EDC curve computation, a higher quality score is assumed to indicate higher utility. For a typical EDC setup, samples with lower quality will therefore be discarded first.

class fiqat.edc.EdcSamplePair

Bases: TypedDict

The input data for one sample pair that is required to compute an EDC curve.

samples: tuple[EdcSample, EdcSample]

Data for the individual samples (EdcSample).

similarity_score: float

The fiqat.types.SimilarityScore for the sample pair.

class fiqat.edc.EdcErrorType(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

An error type for an EDC plot. The error is typically plotted on the Y-axis.

FNMR = 'FNMR'

The FNMR (False Non-Match Rate).

FMR = 'FMR'

The FMR (False Match Rate).

fiqat.edc.PairQualityScoreFunction

A function that combines the two quality scores of the EdcSamplePair.samples (EdcSample.quality_score) into a pairwise quality score.

Typically this should be the min function, since this will correspond to discarding samples (and their sample pairs) in the ascending order of their individual quality scores. See also “Considerations on the Evaluation of Biometric Quality Assessment Algorithms” section I.A.

alias of Callable[[float, float], float]

class fiqat.edc.EdcOutput

Bases: TypedDict

The output of compute_edc() that represents a computed EDC curve.

Only the EdcOutput.error_type, EdcOutput.error_fractions, and the EdcOutput.discard_fractions are required to plot the EDC curve.

error_type: EdcErrorType

The EdcErrorType of the EDC curve.

error_fractions: ndarray

The error fraction values of the EDC curve. Typically plotted on the Y-axis. At each index the value corresponds to the EdcOutput.discard_fractions value at the same index.

discard_fractions: ndarray

The discard fraction values of the EDC curve. Typically plotted on the X-axis. At each index the value corresponds to the EdcOutput.error_fractions value at the same index.

error_counts: ndarray

The discrete integer counts of remaining errors. This is used to compute the EdcOutput.error_fractions. At each index the value corresponds to the EdcOutput.discard_counts value at the same index.

discard_counts: ndarray

The discrete integer discard counts. This is used to compute the EdcOutput.discard_fractions. At each index the value corresponds to the EdcOutput.error_counts value at the same index.

comparison_count: int

The total number of comparisons.

fiqat.edc.compute_edc(error_type: ~fiqat.edc.EdcErrorType, sample_pairs: list[~fiqat.edc.EdcSamplePair], similarity_score_threshold: float | None = None, similarity_score_quantile: float | None = None, starting_error: float | None = None, pair_quality_score_function: ~typing.Callable[[float, float], float] = <built-in function min>) → EdcOutput

Computes an EDC curve.

Parameters:
Returns:

The data for the computed EDC curve.

Return type:

EdcOutput

fiqat.edc.compute_edc_pauc(edc_output: EdcOutput, discard_fraction_limit: float) → float

This computes the pAUC value for the given EDC curve (with stepwise interpolation).

Note that this does not automatically subtract the “area under theoretical best” value, as done in the paper “Finger image quality assessment features - definitions and evaluation”. You can get that value by calling compute_edc_area_under_theoretical_best() with the same parameters, and subtract the result thereof from the pAUC value result of this function (compute_edc_pauc(edc_output, discard_fraction_limit) - compute_edc_area_under_theoretical_best(edc_output, discard_fraction_limit)).

Parameters:
Returns:

The computed pAUC value.

Return type:

float

fiqat.edc.compute_edc_area_under_theoretical_best(edc_output: EdcOutput, discard_fraction_limit: float) → float

Computes the “area under theoretical best” up to the specified discard_fraction_limit. I.e. the area under the line defined by max(0, error_at_0%_discard minus discard_fraction_limit), the “error_at_0%_discard” being the EdcOutput.error_fractions value at index 0.

This is commonly subtracted from the compute_edc_pauc() value returned for the same parameters.

Parameters:

  • edc_output (EdcOutput) – The EDC curve data as returned by the compute_edc() function. The only required part is the EdcOutput.error_fractions array.

  • discard_fraction_limit (float) – The discard fraction cutoff point for the area.

Returns:

The computed “area under theoretical best” value.

Return type:

float

fiqat.edc.compute_error_per_discard_count(edc_output: EdcOutput) → ndarray

Compute the error fractions for all discard counts from 0 to the EdcOutput.comparison_count - 1 (with stepwise interpolation). This data isn’t usually needed for EDC plots, but it can be used e.g. to compute curve combinations.

Parameters:

edc_output (EdcOutput) – The EDC data as returned by the compute_edc() function. The required parts are the EdcOutput.comparison_count, EdcOutput.error_fractions, and the EdcOutput.discard_counts.

Returns:

An array containing the error fractions with each index being a discard count. The size of the array is equal to the EdcOutput.comparison_count.

Return type:

np.ndarray

fiqat.image module

Utility functionality to load and save image files.

fiqat.image.load_image_from_path(path: Path, channels: ImageChannelType) → TypedNpImage

Loads an image file from the given path, and converts the loaded image data to the given fiqat.types.ImageChannelType if necessary.

  • Uses either cv2.imread or cv2.imdecode to load an image file.

  • Can load .bz2 compressed images (e.g. .ppm.bz2 files).

  • Can load .jp2 compressed images via matplotlib.image.imread.

  • Can load .jxl (JPEG XL) compressed images if the djxl command-line tool is available, which currently first decodes the image file to a temporary file (using fiqat.temp.get_temp_path()).

Parameters:

  • path (Path) – The path to the image file.

  • channels (ImageChannelType) – The requested channel type for the returned image data.

Returns:

The loaded image data with the requested fiqat.types.ImageChannelType.

Return type:

TypedNpImage

fiqat.image.load_input_image(input_image: Path | ndarray | Image, channels: ImageChannelType, always_copy: bool = False) → TypedNpImage

Loads and/or converts the input_image as an 8bit-per-channel image with the given channels value.

Parameters:

  • input_image (InputImage) – If the input_image is a Path, load_image_from_path() will be called. Otherwise the input_image will be converted to fit the given channels value if necessary.

  • channels (ImageChannelType) – The requested channel type for the returned image data.

  • always_copy (bool) – If True, a copy of the input image data will be returned even if no file loading or channel conversion was necessary.

Returns:

The image data with the requested fiqat.types.ImageChannelType.

Return type:

TypedNpImage

fiqat.image.save_image(path: Path, input_image: Path | ndarray | Image)

Saves the input_image as a file to the given path.

Parameters:

  • path (Path) –

    The path at which the image should be saved.

    The suffix determines the image format. Images are saved using cv2.imwrite.

    Saving images as lossless .jxl (JPEG XL) files is also supported. This requires the cjxl command-line tool. Unless if input_image is a path to an image file supported by cjxl, a temporary file (using fiqat.temp.get_temp_path()) will first be saved via cv2.imwrite to serve as cjxl input for the actual file destination.

  • input_image (fiqat.types.InputImage) – The image that is to be saved. Besides image data, this can also be a path to an existing image file, e.g. to convert .png to .jxl images or vice versa.

fiqat.iterate module

This module contains utility functionality for iteration.

fiqat.iterate.iterate_as_batches(iterable: Iterable, batch_size: int) → Iterable[Iterable]

Iterate the input in batches.

Parameters:

  • iterable (Iterable) – The iterable that should be iterated through in batches.

  • batch_size (int) – The length of each batch. The final batch may have a smaller length if the input iterable length isn’t exactly divisible by this.

Returns:

This function is a generator that yields batches obtained from the input iterable. If the iterable supports getting the length (len(iterable)) and slicing (iterable[i:j]), each batch will be a slice. Otherwise each batch will be a list constructed by iterating over the iterable. The order of the batches and items therein should remain identical to the input iterable, unless if the slicing behavior differs (e.g. for some custom type).

Return type:

Iterable[Iterable]

fiqat.main_api module

This module contains the main API functions of the toolkit.

All main API functions support processing of either single or multiple input items (i.e. an Iterable). The reason for supporting iterable input is to enable method implementations to support possibly more computationally efficient batched processing of the input items (e.g. for deep learning models executed on a GPU).

If one input item is given, one output item is returned. If multiple input items are given, then multiple output items will be returned in the same order. For multiple inputs, note that methods canonically act as iterators, so that results will be computed during iteration. I.e. for a long list of inputs not all outputs are immediately computed when the function is called, since the functions act as generators when multiple inputs are used.

Every function takes arbitrary keyword arguments (**kwargs) that are passed to the concrete method implementations, to allow for different configurations. E.g. included methods that support running on a CPU or GPU can be configured by passing a device_config keyword argument of type fiqat.types.DeviceConfig. Available configuration options and their default values can be queried via fiqat.registry.get_method().

Other configuration data specific to your local installation is handled via the fiqat.config module. E.g. the local paths to required model files.

While the toolkit does define canonical input/output types for the included methods of each fiqat.types.MethodType, custom methods can easily use different types if needed.

fiqat.main_api.detect_faces(method_id: PurePath | str, images: Path | ndarray | Image | Iterable[Path | ndarray | Image], tqdm_config: bool | tuple | list | dict = True, **kwargs) → FaceDetectorOutput | Iterable[FaceDetectorOutput]

Detect faces using the specified face detector.

Parameters:

  • method_id (fiqat.types.MethodIdStr) – Specifies the face detector. The IDs start with ‘fd/’ (see fiqat.types.MethodType.FACE_DETECTOR).

  • images (fiqat.types.InputImages) – One image or multiple images that should be processed. Note that you can also pass paths to image files (see fiqat.types.InputImage).

  • tqdm_config (Union[bool, tuple, list, dict]) – If not False and if the input is iterable, fiqat.term.tqdm() will be called to show a progress bar. The default progress bar description is the API function name followed by the method_id.

  • **kwargs – Keyword arguments passed to the method.

Returns:

One or multiple output items. See the fiqat.main_api module description for general method output behavior.

Return type:

fiqat.types.FaceDetectorOutputs

fiqat.main_api.estimate_primary_faces(method_id: PurePath | str, face_detector_output: FaceDetectorOutput | Iterable[FaceDetectorOutput], tqdm_config: bool | tuple | list | dict = True, **kwargs) → PrimaryFaceEstimate | Iterable[PrimaryFaceEstimate]

Select a primary face for fiqat.types.FaceDetectorOutput data (e.g. from a detect_faces() call), to handle cases in which multiple faces were detected in an image with only one relevant face.

Parameters:
Returns:

One or multiple output items. See the fiqat.main_api module description for general method output behavior.

Return type:

fiqat.types.PrimaryFaceEstimates

fiqat.main_api.preprocess_images(method_id: PurePath | str, primary_face_estimates: PrimaryFaceEstimate | Iterable[PrimaryFaceEstimate], tqdm_config: bool | tuple | list | dict = True, **kwargs) → TypedNpImage | Iterable[TypedNpImage]

Preprocess an image based on fiqat.types.PrimaryFaceEstimate data (e.g. from a estimate_primary_faces() call). Each fiqat.types.PrimaryFaceEstimate points to a specific detected face in a fiqat.types.FaceDetectorOutput, and each fiqat.types.FaceDetectorOutput also contains the corresponding fiqat.types.InputImage.

Parameters:
Returns:

One or multiple output items. See the fiqat.main_api module description for general method output behavior.

Return type:

fiqat.types.TypedNpImages

fiqat.main_api.assess_quality(method_id: PurePath | str, images: Path | ndarray | Image | Iterable[Path | ndarray | Image], tqdm_config: bool | tuple | list | dict = True, **kwargs) → float | Iterable[float]

Assess the quality of a face image. Usually the image should be preprocessed (e.g. from a preprocess_images() call).

Parameters:
Returns:

One or multiple output items. See the fiqat.main_api module description for general method output behavior.

Return type:

fiqat.types.QualityScores

fiqat.main_api.extract_face_recognition_features(method_id: PurePath | str, images: Path | ndarray | Image | Iterable[Path | ndarray | Image], tqdm_config: bool | tuple | list | dict = True, **kwargs) → ndarray | Iterable[ndarray]

Extract a feature vector for face recognition from a face image. Usually the image should be preprocessed (e.g. from a preprocess_images() call).

Parameters:
Returns:

One or multiple output items. See the fiqat.main_api module description for general method output behavior.

Return type:

fiqat.types.FeatureVectors

fiqat.main_api.compute_comparison_scores(method_id: PurePath | str, feature_vector_pairs: tuple[ndarray, ndarray] | Iterable[tuple[ndarray, ndarray]], tqdm_config: bool | tuple | list | dict = True, **kwargs) → float | Iterable[float]

Compute a comparison score for a pair of feature vectors for face recognition (each e.g. from a extract_face_recognition_features() call). Note that the comparison score computation method must fit to the used feature vector extration method to obtain sensible results.

Parameters:
Returns:

One or multiple output items. See the fiqat.main_api module description for general method output behavior. Note that the methods included in the toolkit all canonically return fiqat.types.SimilarityScores, i.e. fiqat.types.ComparisonScores of type fiqat.types.ComparisonScoreType.SIMILARITY.

Return type:

fiqat.types.ComparisonScores

fiqat.main_api.process(method_id: PurePath | str, input_items: Any | Iterable[Any], tqdm_config: bool | tuple | list | dict = True, **kwargs) → Any | Iterable[Any]

This general processing function will call one of the other main API functions based on the fiqat.types.MethodType that can be read from the fiqat.types.MethodIdStr.

Parameters:

  • method_id (fiqat.types.MethodIdStr) – Specifies the method.

  • input_items (Union[Any, Iterable[Any]]) – One or multiple items that should be processed.

  • tqdm_config (Union[bool, tuple, list, dict]) – If not False and if the input is iterable, fiqat.term.tqdm() will be called to show a progress bar. The default progress bar description is the API function name followed by the method_id.

  • **kwargs – Keyword arguments passed to the method.

Returns:

One or multiple output items. See the fiqat.main_api module description for general method output behavior.

Return type:

Union[Any, Iterable[Any]]

fiqat.patch module

This module patches numpy by reactivating aliases deprecated in version 1.20.0, since some of the included methods still rely on older dependencies which in turn use these aliases:

  • np.bool

  • np.float

  • np.int

fiqat.registry module

The toolkit’s registry system that contains entries for the various available methods.

fiqat.registry.registry_data = {PurePosixPath('csc/arcface'): {'info': None, 'loader': <function _loader>, 'method_entry': None, 'status': MethodRegistryStatus.UNKNOWN}, PurePosixPath('fd/dlib'): {'info': None, 'loader': <function _loader>, 'method_entry': None, 'status': MethodRegistryStatus.UNKNOWN}, PurePosixPath('fd/mtcnn'): {'info': None, 'loader': <function _loader>, 'method_entry': None, 'status': MethodRegistryStatus.UNKNOWN}, PurePosixPath('fd/retinaface'): {'info': None, 'loader': <function _loader>, 'method_entry': None, 'status': MethodRegistryStatus.UNKNOWN}, PurePosixPath('fd/scrfd'): {'info': None, 'loader': <function _loader>, 'method_entry': None, 'status': MethodRegistryStatus.UNKNOWN}, PurePosixPath('fiqa/crfiqa'): {'info': None, 'loader': <function _loader>, 'method_entry': None, 'status': MethodRegistryStatus.UNKNOWN}, PurePosixPath('fiqa/faceqnet'): {'info': None, 'loader': <function _loader>, 'method_entry': None, 'status': MethodRegistryStatus.UNKNOWN}, PurePosixPath('fiqa/magface'): {'info': None, 'loader': <function _loader>, 'method_entry': None, 'status': MethodRegistryStatus.UNKNOWN}, PurePosixPath('fr/arcface'): {'info': None, 'loader': <function _loader>, 'method_entry': None, 'status': MethodRegistryStatus.UNKNOWN}, PurePosixPath('pfe/sccpfe'): {'info': None, 'loader': <function _loader>, 'method_entry': None, 'status': MethodRegistryStatus.UNKNOWN}, PurePosixPath('prep/crop'): {'info': None, 'loader': <function _loader>, 'method_entry': None, 'status': MethodRegistryStatus.UNKNOWN}, PurePosixPath('prep/simt'): {'info': None, 'loader': <function _loader>, 'method_entry': None, 'status': MethodRegistryStatus.UNKNOWN}}

The toolkit’s method registry data.

Each key is a fiqat.types.MethodId and each value is a fiqat.types.RegistryEntry.

By default it will contain entries for the toolkit’s internally provided methods. Custom methods registered via register_method() or register_method_loader() are also added herein.

fiqat.registry.get_method_type_from_id(method_id: PurePath) → MethodType

Reads the fiqat.types.MethodType from the given fiqat.types.MethodId.

Parameters:

method_id (fiqat.types.MethodId) –

A valid fiqat.types.MethodId, meaning that

  1. the fiqat.types.MethodId must have two or more parts (e.g. the two parts “<method-type>/<method-name>”), and

  2. the first part, which specifies the fiqat.types.MethodType, must be a valid fiqat.types.MethodType.

Returns:

The fiqat.types.MethodType read from the given fiqat.types.MethodId.

Return type:

MethodType

fiqat.registry.register_method_loader(method_id: PurePath | str, loader: Callable[[], tuple[MethodRegistryStatus, str | Exception | None]])

Register a method by specifying a fiqat.types.MethodRegistryLoader function.

This is meant for methods for which the dependencies aren’t loaded yet, and for which the availability of those dependencies isn’t known in advance, which is relevant for the toolkit’s internally provided methods. Custom methods with already loaded (or known to be available) dependencies should usually be registered via register_method() instead.

The initial fiqat.types.RegistryEntry.status will be fiqat.types.MethodRegistryStatus.UNKNOWN. See get_method() for the loading procedure that is executed when the method is requested.

Parameters:
fiqat.registry.register_method(method_entry: MethodRegistryEntry)

Register a method that is known to be available for use by specifying the fiqat.types.MethodRegistryEntry data.

The initial fiqat.types.RegistryEntry.status will be fiqat.types.MethodRegistryStatus.AVAILABLE.

Parameters:

method_entry (fiqat.types.MethodRegistryEntry) – The new method entry data. This function will assert that the fiqat.types.MethodRegistryEntry.method_id hasn’t been used to register a method previously.

fiqat.registry.get_method(method_id: PurePath | str, check_method_type: MethodType | None = None) → MethodRegistryEntry

Returns the fiqat.types.MethodRegistryEntry for the requested fiqat.types.MethodId.

If the method has not yet been loaded (i.e. fiqat.types.RegistryEntry.status is fiqat.types.MethodRegistryStatus.UNKNOWN), then the fiqat.types.MethodRegistryLoader function will be called. If it the loading was successful, the fiqat.types.RegistryEntry.status will become fiqat.types.MethodRegistryStatus.AVAILABLE and the fiqat.types.MethodRegistryEntry is returned. Otherwise the fiqat.types.RegistryEntry.status will become fiqat.types.MethodRegistryStatus.UNAVAILABLE and a RuntimeError is raised.

Note that if you want to get the fiqat.types.RegistryEntry instead of the fiqat.types.MethodRegistryEntry, you can simply inspect the registry_data dictionary directly.

Parameters:
Returns:

The entry for the fiqat.types.MethodRegistryStatus.AVAILABLE method.

Return type:

fiqat.types.MethodRegistryEntry

Raises:

RuntimeError – If the fiqat.types.RegistryEntry.status is fiqat.types.MethodRegistryStatus.UNAVAILABLE.

fiqat.serialize module

This module defines a simple schema-less binary serialization format used by the fiqat.storage.StorageSqlite utility. Using this serialization format is completely optional, the other parts of the toolkit do not require it.

Like JSON this format is schema-less, meaning that the object type and structure is part of the encoding. Unlike JSON it is a “binary” format that e.g. directly encodes integers in network byte order (i.e. big-endian), instead of formatting them as text.

This makes it conceptually similar to e.g. MsgPack. Except in contrast to general formats, such as MsgPack, this specialized format natively supports encoding of various common Python types, as well as common numpy types (e.g. np.ndarray), and some toolkit-specific types (fiqat.types.namedtuple_types and fiqat.types.enum_types). See PackableItem and PackType. It also supports the direct encoding of circular object references for the types dict, list, and set. Additionally, each np.ndarray and each distinct string and path can likewise be stored only once, further occurrences being encoded as references. Path parts are optionally treated as separate strings too.

There are three reasons for why this format was written:

  • Since Python’s pickle serialization is not secure, a different serialization format should be used for any data that might be shared between users. This constrained format should be comparatively secure (i.e. it should not be possible to execute arbitrary code).

  • Existing general schema-less formats such as JSON or MsgPack still require additional specialization functions to handle (de)serialization of various Python types. This specialized format can support such types natively.

  • Albeit perhaps less important, this custom format supports the automatic encoding of references to already encoded objects, including support for circular references. Other formats such as JSON or MsgPack do not support this directly.

Additionally the format may have these advantages:

  • This binary format should usually be more compact than textual formats such as JSON, which may be beneficial when larger quantities of data are stored.

  • The (de)serialization is simple and written in pure Python code. It consists only of a single, short file, which means that it should be fairly straightforward to check or customize it if necessary.

Possible disadvantages:

  • There currently is no comprehensive automatic testing of this module.

  • Some features reduce (de)serialization speed (e.g. string deduplication).

  • The code for newer versions has become a bit more complicated due to various features.

  • No other language implementations are planned.

fiqat.serialize.PackableItem

The union of the (de)serializable types.

The fiqat.types.namedtuple_types and fiqat.types.enum_types are also (de)serializable.

For int values, note that the serialization format currently only supports values that still fit into an unsigned or signed 64bit integer at most.

alias of dict | list | str | int | float | ndarray | Path | PurePath

class fiqat.serialize.PackType(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

The distinguished serialization type IDs, stored as 8bit unsigned integers.

DICT = 0

A dictionary.

LIST = 1

A list.

TUPLE = 2

A tuple.

STR = 3

A UTF-8 encoded string (str).

FLOAT_32 = 4

A IEEE 754 binary32 floating-point number.

This is currently never encoded by pack(), but supported by unpack() (decoded as a Python float, i.e. converted to IEEE 754 binary64).

FLOAT_64 = 5

A Python float, i.e. a IEEE 754 binary64 floating-point number.

INT_8 = 6

A Python int packed as an 8bit signed integer.

INT_16 = 7

A Python int packed as a 16bit signed integer.

INT_32 = 8

A Python int packed as a 32bit signed integer.

INT_64 = 9

A Python int packed as a 64bit signed integer.

UINT_8 = 10

A Python int packed as an 8bit unsigned integer.

UINT_16 = 11

A Python int packed as a 16bit unsigned integer.

UINT_32 = 12

A Python int packed as a 32bit unsigned integer.

UINT_64 = 13

A Python int packed as a 64bit unsigned integer.

NUMPY_ARRAY = 14

An np.ndarray packed via np.save(..., allow_pickle=False) and unpacked via np.load(..., allow_pickle=False).

NUMPY_FLOAT_32 = 15

An np.float32 (IEEE 754 binary32 floating-point number).

NUMPY_FLOAT_64 = 16

An np.float64 (IEEE 754 binary64 floating-point number).

NUMPY_INT_8 = 17

An np.int8 (8bit signed integer).

NUMPY_INT_16 = 18

An np.int16 (16bit signed integer).

NUMPY_INT_32 = 19

An np.int32 (32bit signed integer).

NUMPY_INT_64 = 20

An np.int64 (64bit signed integer).

NUMPY_UINT_8 = 21

An np.uint8 (8bit unsigned integer).

NUMPY_UINT_16 = 22

An np.uint16 (16bit unsigned integer).

NUMPY_UINT_32 = 23

An np.uint32 (32bit unsigned integer).

NUMPY_UINT_64 = 24

An np.uint64 (64bit unsigned integer).

POSIX_PATH = 25

A pathlib.PosixPath.

Beginning with format version 4: Concrete path types can only be instantiated on the matching system. unpack() will load this as a pathlib.Path, which depending on the system is either a pathlib.PosixPath or a pathlib.WindowsPath.

WINDOWS_PATH = 26

A pathlib.WindowsPath.

Beginning with format version 4: Concrete path types can only be instantiated on the matching system. unpack() will load this as a pathlib.Path, which depending on the system is either a pathlib.PosixPath or a pathlib.WindowsPath.

PURE_POSIX_PATH = 27

A pathlib.PurePosixPath.

PURE_WINDOWS_PATH = 28

A pathlib.PureWindowsPath.

NONE = 29

A None value.

FIQAT_NAMEDTUPLE = 30

One of the fiqat.types.namedtuple_types. The types are packed using their UTF-8 encoded string name.

FIQAT_ENUM = 31

One of the fiqat.types.enum_types. The types are packed using their UTF-8 encoded string name.

REFERENCE = 32

A reference to a previously encoded DICT, LIST, NUMPY_ARRAY, STR, or *_PATH. During encoding, the DICT, LIST, and NUMPY_ARRAY objects are tracked via their Python id. STR and *_PATH instances are tracked by their string value (i.e. each will be stored only once). During decoding, an already decoded object will be used here. The encoded reference is a 64bit unsigned integer that represents the index of the object in order of encoding.

BYTES = 33

A Python bytes string.

SET = 34

A set.

Added in format version 5.

fiqat.serialize.serializer_version = 5

The current version of the serialization format, encoded at the start as a 64bit unsigned integer.

fiqat.serialize.pack(file: BinaryIO, item: dict | list | str | int | float | ndarray | Path | PurePath, paths_as_parts: bool = False)

Serializes the item to the file.

Parameters:

  • file (BinaryIO) – The destination for the serialized data.

  • item (PackableItem) – The object that is to be serialized.

  • paths_as_parts (bool) – If True, the parts of pathlib paths will be serialized as individual strings, which allows for deduplication for these string parts. This can result in smaller serialized data, but can also affect the serialization & deserialization speed. If False, one path is serialized as one string.

fiqat.serialize.unpack(file: BinaryIO) → dict | list | str | int | float | ndarray | Path | PurePath

Deserializes an object read from the file.

Parameters:

file (BinaryIO) – The source of the serialized data.

Returns:

The deserialized object.

Return type:

PackableItem

fiqat.storage module

Utility functionality to store and load computed experiment data.

class fiqat.storage.StorageBase

Bases: ABC

Abstract base class for the data storage utility functionality.

abstract open(path: Path)

Initializes the storage class. This method has to be called before any of the other methods may be used.

Parameters:

path (Path) – The path at which the data is or will be stored.

abstract load_items(item_type_id: str) → Iterable[Any]

Iteratively load all items for the given type.

Parameters:

item_type_id (str) – The type of the items that should be loaded.

Returns:

The loaded items.

Return type:

Iterable[Any]

abstract update_item(item_type_id: str, item_key: str, item: Any)

Add or overwrite an item in the storage. Note that the storage implementation may not immediately write the update to disk - see the save() method.

Parameters:

  • item_type_id (str) – The type of the item.

  • item_key (str) – The identifier key of the item.

  • item (Any) – The item data itself.

abstract save()

Save any pending updates to disk.

An implementation may also write to disk immediately in the update_item(), in which case this method may do nothing.

abstract close()

Calls save() and then closes any open file handles. The open() method has to be called again before any of the other methods may be used.

class fiqat.storage.StorageSqlite(save_on_update_after_sec: float = 60)

Bases: StorageBase

A StorageBase implementation that stores data in a sqlite3 database.

The stored items are serialized using the fiqat.serialize module.

Parameters:

save_on_update_after_sec (float) – If set to a duration in seconds >= 0, then save() will be called at the end of a update_item() call, when the elapsed time since the last save() call is greater than or equal to this setting. I.e. save() is always called in update_item() if this is 0.

con

The sqlite3 database connection obtained by sqlite3.connect in the open() method.

last_save_time

The time of the last save() call (using the value from time.monotonic()).

save_on_update_after_sec

See the corresponding StorageSqlite constructor parameter description.

open(path: Path)

Initializes the storage class by opening the SQLite database (sqlite3.connect). This method has to be called before any of the other methods may be used.

Parameters:

path (Path) – The path at which the SQLite database is or will be stored (e.g. with the suffix ‘.sqlite3’).

count_items(item_type_id: str) → int

Counts the number of items for a given item type ID.

Parameters:

item_type_id (str) – The type of the items that should be counted.

Returns:

The number of the stored items.

Return type:

int

load_items(item_type_id: str) → Iterable[Any]

Iteratively load all items for the given type.

Parameters:

item_type_id (str) – The type of the items that should be loaded.

Returns:

The loaded items.

Return type:

Iterable[Any]

load_item_keys(item_type_id: str) → Iterable[str]

Like load_items(), but only loads the item keys. If only the keys are needed, this can be faster since the item values aren’t deserialized.

Parameters:

item_type_id (str) – The type of the items for which the keys should be loaded.

Returns:

The loaded item keys.

Return type:

Iterable[str]

load_item(item_type_id: str, item_key: str) → Any | None

Loads a single item with a specific key.

Parameters:

  • item_type_id (str) – The type of the item

  • item_key (str) – The identifier key of the item.

Returns:

The loaded item or None if no entry exists.

Return type:

Optional[Any]

update_item(item_type_id: str, item_key: str, item: Any)

Add or overwrite an item in the storage.

The save() method may automatically be called at the end; see the save_on_update_after_sec constructor setting of StorageSqlite.

Parameters:

  • item_type_id (str) – The type of the item. This is used as the table name in the SQLite database. The table will be created if doesn’t exist yet. Each table has a “key” (string content, i.e. SQLite TEXT) and a “value” (binary content, i.e. SQLite BLOB) column.

  • item_key (str) – The identifier key of the item. This corresponds to the “key” column of the SQLite table.

  • item (Any) – The item data itself. It is serialized via fiqat.serialize.pack() and stored in the “value” column of the SQLite table.

save()

Commits any pending updates to the database.

close()

Calls save() and then closes the connection to the database. The open() method will have to be called again before any of the other methods can be used again.

fiqat.temp module

Utility functionality to handle temporary files and directories.

fiqat.temp.get_temp_dir() → Path

Creates a with statement context manager that returns a directory meant for temporary files.

If a ‘temp_dir’ path is set in the fiqat.config.config_data (see get_config_data()), then this path will be returned (the directory will be created first if it doesn’t exist already). Otherwise tempfile.TemporaryDirectory() will be used.

Examples

>>> with get_temp_dir() as temp_dir:
...   # ... create and process temporary files within temp_dir ...
fiqat.temp.get_temp_path(suffix: str, unlink: bool = True) → Path

Creates a with statement context manager that returns a path meant for a temporary file that does not exist yet.

The path will be created within a temporary directory given by a get_temp_dir() call.

Parameters:

  • suffix (str) – The filename is formatted as f'{time.monotonic_ns()}{suffix}'.

  • unlink (bool) – If True, then on the exit of the context manager .unlink() will be called on the path, if it .exists(). I.e. this will automatically remove a created temporary file.

Examples

>>> with get_temp_path(suffix='test', unlink=True) as temp_path:
...   with open(temp_path, 'w') as file:
...     # ... write something to the file ...
...   # ... use the created temporary file, e.g. as input for some command line tool ...
...
... # Since unlink=True, the temp_path will be automatically removed after the with statement.

fiqat.term module

Terminal support functionality.

This attempts to import colorama and termcolor, calling colorama.init(), and re-exports termcolor.colored and termcolor.cprint. For this the module will catch any ImportError and provide fallback functions that omit coloring.

Besides coloring the module also provides a tqdm helper function for progress bars.

fiqat.term.tqdm(output_items: Iterable, *tqdm_args, input_items: Any | None = None, tqdm_config: bool | tuple | list | dict = False, **tqdm_kwargs) → Iterable

Helper function that wraps the tqdm.tqdm progress bar function.

This is mostly intended for the main API function implementation. Besides the described parameters, it will set a default value for the colour keyword argument if a tqdm.colour value is set in the toolkit config file (fiqat.config).

Parameters:

  • output_items (Iterable) – The output items that will be passed as the first argument to tqdm.tqdm.

  • *tqdm_args (tuple) – Other positional arguments for tqdm.tqdm (starting with the second argument, output_items being the first).

  • input_items (Optional[Any]) – If set the total parameter value will be len(input_items) (TypeError``s are silently caught). This can be useful if the total would not be automatically inferred from the ``output_items parameter.

  • tqdm_config (Union[bool, tuple, list, dict]) – If set to a tuple or list, this will be appended to the tqdm_args. If set to a dict, this will be merged into the tqdm_kwargs.

  • **tqdm_kwargs (dict) – Other keyword arguments for tqdm.tqdm.

fiqat.types module

The common types used in the toolkit.

fiqat.types.MethodId

A method in the toolkit is identified by a path that starts with the corresponding MethodType string value, and continues with one or more arbitrary name parts.

For example, MethodId(‘fd/abc’) would be a MethodType.FACE_DETECTOR (i.e. ‘fd’) method called ‘abc’.

Using a path for such IDs allows for canonically nested identifier groups, e.g. ‘fiqa/abc/xyz1’ and ‘fiqa/abc/xyz2’, analgous to files and directories in a filesystem.

alias of PurePath

fiqat.types.MethodIdStr

For convenience, a MethodId can also be passed as a string to some functions, such as the functions that comprise the toolkit’s main API (fiqat.main_api).

alias of PurePath | str

class fiqat.types.DeviceConfig(type: str, index: int)

Bases: NamedTuple

Specifies the device type (often ‘cpu’) and index (often 0) for method execution. While methods typically support CPU execution, not all methods support GPU execution.

type: str

The device type, either ‘cpu’ or ‘gpu’.

index: int

The index of the device, e.g. 0 for first device of the type.

class fiqat.types.MethodType(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

String-enum identifiers for the method types that are supported by the toolkit.

FACE_DETECTOR = 'fd'

Main API function: fiqat.main_api.detect_faces()

Face detector methods detect face bounding-boxes (aka the face region-of-interest) and/or facial landmarks within an image. Face detectors may detect zero, one, or multiple faces within an image, and may also provide confidence values for each detected face.

See the FaceDetectorOutput type for the canonical face detector output structure of the toolkit.

FD = 'fd'

Alias for MethodType.FACE_DETECTOR.

PRIMARY_FACE_ESTIMATOR = 'pfe'

Main API function: fiqat.main_api.estimate_primary_faces()

Primary face estimator methods take FaceDetectorOutput and heuristically select one “primary” face, e.g. by choosing the one with the largest bounding-box area. This can help with images which are supposed to depict one primary face, but may accidentally show other faces e.g. in the background. It can also help when face detectors erroneously detected faces.

See the PrimaryFaceEstimate type for the canonical primary face estimator output structure of the toolkit.

PFE = 'pfe'

Alias for MethodType.PRIMARY_FACE_ESTIMATOR.

PREPROCESSOR = 'prep'

Main API function: fiqat.main_api.preprocess_images()

Face image preprocessors adjust images based on PrimaryFaceEstimate, usually by aligning the image to certain landmarks in the FaceDetectorOutput, and by cropping and resizing the image.

The preprocessed image is canonically returned as a TypedNpImage and can be saved and used for further processing, e.g. as input for MethodType.FACE_IMAGE_QUALITY_ASSESSMENT_ALGORITHM or MethodType.FACE_RECOGNITION_FEATURE_EXTRACTOR methods.

PREP = 'prep'

Alias for MethodType.PREPROCESSOR.

FACE_IMAGE_QUALITY_ASSESSMENT_ALGORITHM = 'fiqa'

Main API function: fiqat.main_api.assess_quality()

Face image quality assessment algorithms take a (usually preprocessed) image as input and assess the quality (often in terms of the image’s utility for face recognition).

Canonically the result is a scalar QualityScore, higher values indicating better quality.

QUALITY_ASSESSOR = 'fiqa'

Alias for MethodType.FACE_IMAGE_QUALITY_ASSESSMENT_ALGORITHM.

FIQA = 'fiqa'

Alias for MethodType.FACE_IMAGE_QUALITY_ASSESSMENT_ALGORITHM.

FACE_RECOGNITION_FEATURE_EXTRACTOR = 'fr'

Main API function: fiqat.main_api.extract_face_recognition_features()

Feature extractors take a (usually preprocessed) image as input and canonically return a FeatureVector. These can be used for face recognition, by comparing pairs (FeatureVectorPair).

FEATURE_EXTRACTOR = 'fr'

Alias for MethodType.FACE_RECOGNITION_FEATURE_EXTRACTOR.

FR = 'fr'

Alias for MethodType.FACE_RECOGNITION_FEATURE_EXTRACTOR.

COMPARISON_SCORE_COMPUTATION = 'csc'

Main API function: fiqat.main_api.compute_comparison_scores()

This method type computes a ComparisonScore for a FeatureVectorPair. The toolkit’s provided methods will canonically return similarity scores (ComparisonScoreType.SIMILARITY), meaning that higher values indicate higher similarity between the faces represented by the feature vectors.

CSC = 'csc'

Alias for MethodType.COMPARISON_SCORE_COMPUTATION.

class fiqat.types.MethodRegistryStatus(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Modules for methods included in the toolkit are lazily loaded, and different methods are allowed to require incompatible Python environment setups. This enum states the status of the methods.

UNKNOWN = 'unknown'

There was no attempt to load the method yet.

AVAILABLE = 'available'

The method has been loaded and is available (and should remain available).

UNAVAILABLE = 'unavailable'

The method could not been loaded, usually due to missing or incompatible dependencies.

fiqat.types.MethodRegistryInfo

Information provided after a method load attempt.

alias of str | Exception

fiqat.types.MethodRegistryLoader

Returns the new MethodRegistryStatus and an optional MethodRegistryInfo (e.g. about missing dependencies).

alias of Callable[[], tuple[MethodRegistryStatus, str | Exception | None]]

fiqat.types.MethodProcessFunction

A MethodRegistryEntry.process function. This can be called by the toolkit’s main API functions (fiqat.main_api).

Thr first parameter is the MethodRegistryEntry.

The second parameter is a dictionary with configuration options. The default values of this dictionary are specified by MethodRegistryEntry.default_config. Overwriting values or other values are specified by the keyword arguments (**kwargs) to the main API functions (fiqat.main_api).

The third paramter is an Iterable over the input items.

The result is an Iterable over the output items, in the same order as the input items (each output item corresponding to one input item). Typically this function is implemented as a generator, i.e. using yield to iteratively produce output items.

alias of Callable[[TypedDict, dict, Iterable], Iterable]

class fiqat.types.MethodRegistryEntry

Bases: TypedDict

The toolkit tracks methods in a registry (fiqat.registry) with the general RegistryEntry type. This MethodRegistryEntry type contains further method-specific data for loaded (i.e. MethodRegistryStatus.AVAILABLE) methods.

method_id: PurePath

The identifier of the method.

process: Callable[[TypedDict, dict, Iterable], Iterable]

The MethodProcessFunction that can be called by the toolkit’s main API function (fiqat.main_api) that corresponds to the method’s type.

default_config: dict

The method’s available configuration options with their default values.

class fiqat.types.RegistryEntry

Bases: TypedDict

The toolkit tracks methods in a registry (fiqat.registry) using this type for registry entries.

status: MethodRegistryStatus

The availability of the method.

This is mainly relevant for the methods that are included with the toolkit. External custom methods will likely be already loaded when they are registered (and thus MethodRegistryStatus.AVAILABLE).

loader: Callable[[], tuple[MethodRegistryStatus, str | Exception | None]] | None

The loader function for the method. Methods with status MethodRegistryStatus.UNKNOWN aren’t loaded yet, in which case this function will be used to (attempt to) load them.

This is mainly relevant for the methods that are included with the toolkit. External custom methods will likely be already loaded when they are registered, and thus do not need to specify a loader function.

info: str | Exception | None

Information that may be provided by a MethodRegistryLoader call, usually when the loading failed for some reason, such as missing or incompatible dependencies.

method_entry: MethodRegistryEntry | None

The MethodRegistryEntry for methods with MethodRegistryStatus.AVAILABLE status.

class fiqat.types.FdMethodRegistryEntry

Bases: MethodRegistryEntry

MethodRegistryEntry specialization for face detectors (MethodType.FACE_DETECTOR).

landmark_names: list[str]

Names for the landmarks, in the same order as the DetectedFace landmarks lists. These names can be used e.g. to draw labeled landmarks.

Adding names to this list is optional. If there is no landmark name specified at a certain index in this list, then the toolkit’s drawing code (fiqat.draw.draw_face_detector_output()) will fall back to using the index as the label.

method_id: PurePath
process: Callable[[TypedDict, dict, Iterable], Iterable]
default_config: dict
class fiqat.types.QualityScoreRange(min: float, max: float)

Bases: NamedTuple

The minimum and maximum QualityScore that can be produced by a MethodType.FACE_IMAGE_QUALITY_ASSESSMENT_ALGORITHM method.

min: float

The minimum value that may be produced.

max: float

The maximum value that may be produced.

class fiqat.types.FiqaMethodRegistryEntry

Bases: MethodRegistryEntry

Face image quality assessment MethodRegistryEntry.

quality_score_range: QualityScoreRange | None

If specified, the minimum/maximum comparison score that can be produced. If the method is used via the main API, this will be automatically asserted.

method_id: PurePath
process: Callable[[TypedDict, dict, Iterable], Iterable]
default_config: dict
class fiqat.types.ComparisonScoreType(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

The type of a ComparisonScore that defines how the value should be interpreted.

SIMILARITY = 'similarity'

Higher values indicate higher similarity between faces. This is the type canonically used by the toolkit, which is why there also is a SimilarityScore type alias to clarify this usage.

DISSIMILARITY = 'dissimilarity'

Lower values indicate higher similarity between faces.

class fiqat.types.ComparisonScoreRange(min: float, max: float)

Bases: NamedTuple

The minimum and maximum ComparisonScore value that can be produced by a MethodType.COMPARISON_SCORE_COMPUTATION method.

min: float

The minimum value that may be produced.

max: float

The maximum value that may be produced.

class fiqat.types.CscMethodRegistryEntry

Bases: MethodRegistryEntry

MethodRegistryEntry specialization for comparison score computation (MethodType.COMPARISON_SCORE_COMPUTATION).

comparison_score_type: ComparisonScoreType

The method either produces similarity or dissimilarity scores. Methods provided by the toolkit will canonically produce ComparisonScoreType.SIMILARITY scores.

comparison_score_range: ComparisonScoreRange | None

If specified, the minimum/maximum comparison score that can be produced. If the method is used via the main API, i.e. fiqat.main_api.compute_comparison_scores(), this will be asserted automatically.

method_id: PurePath
process: Callable[[TypedDict, dict, Iterable], Iterable]
default_config: dict
class fiqat.types.ImageChannelType(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

The common image channel types that are used within the toolkit.

GRAY = 'gray'

For grayscale images with a single channel.

RGB = 'rgb'

For color images with the RGB (Red,Green,Blue) channel order.

BGR = 'bgr'

For color images with the BGR (Blue,Green,Red) channel order. This order is by cv2 functions used within parts of the toolkit.

class fiqat.types.Cv2ColorTuple(b: int, g: int, r: int)

Bases: NamedTuple

A BGR color tuple, for use by various cv2 functions.

b: int

Blue channel value, usually in the range [0,255].

g: int

Green channel value, usually in the range [0,255].

r: int

Red channel value, usually in the range [0,255].

fiqat.types.NpImage

Image represented as a numpy array.

alias of np.ndarray

class fiqat.types.TypedNpImage(image: ndarray, channels: ImageChannelType)

Bases: NamedTuple

Tuple of an NpImage and the associated ImageChannelType.

image: ndarray

The image data.

channels: ImageChannelType

The channel type of the image data.

fiqat.types.PillowImage

Image type from the Pillow (PIL) library.

alias of PIL.Image.Image

fiqat.types.InputImage

Either a pathlib.Path to an image or image data (NpImage or PillowImage) that can be used as input for the toolkit’s main API functions (fiqat.main_api).

alias of Path | ndarray | Image

class fiqat.types.ImageSize(x: int, y: int)

Bases: NamedTuple

The integer pixel width(x),height(y) of an image.

x: int

The width in pixels as an integer.

y: int

The height in pixels as an integer.

class fiqat.types.FaceRoi(x: float, y: float, width: float, height: float)

Bases: NamedTuple

x,y,width,height pixels of a face ROI (Region Of Interest) rectangle, aka bounding-box. x,y specifies the top-left start coordinates of the rectangle. x+width,y+height specifies the bottom-right end coordinates of the rectangle.

Note that the values are allowed to be floating-point numbers (i.e. not exact pixel integer values).

x: float

The horizontal (left) pixel coordinate.

y: float

The vertical (top) pixel coordinate.

width: float

The width.

height: float

The height.

class fiqat.types.FacialLandmark(x: float, y: float)

Bases: NamedTuple

The floating-point or integer x,y pixel coordinates of a facial landmark in an image.

x: float

The horizontal pixel coordinate.

y: float

The vertical pixel coordinate.

class fiqat.types.DetectedFace

Bases: TypedDict

Face detector information for a single face.

Note that the actual face detector output structure can vary between the face detector methods.

roi: FaceRoi | None

The ROI (Region Of Interest) bounding-box rectangle around the face.

landmarks: list[FacialLandmark] | None

A list of facial landmark points.

Note that different face detectors can provide different facial landmark sets.

confidence: float | None

A confidence value provided by the face detector. Higher values mean higher confidence that a face has been detected.

Note that the range may differ depending on the used face detector.

class fiqat.types.FaceDetectorOutput

Bases: TypedDict

The output of a face detector for one image, which may include multiple DetectedFace instances.

Note that the actual face detector output structure can vary between the face detector methods. For example, different methods can provide different facial landmark sets.

detected_faces: list[DetectedFace]

The detected faces.

input_image_size: ImageSize

The width/height of the input image that was processed by the face detector. This can be used e.g. to normalize the roi and landmarks (which are specified in pixel coordinates).

input_image: Path | ndarray | Image

The input image that was processed by the face detector.

class fiqat.types.PrimaryFaceEstimate(face_detector_output: FaceDetectorOutput, index: int | None)

Bases: NamedTuple

Specifies a primary face by an index for the FaceDetectorOutput.detected_faces list.

face_detector_output: FaceDetectorOutput

The face detector data which is being indexed. Usually the estimate is based on this data too.

index: int | None

The index of the primary face. If there is no primary face (e.g. because the FaceDetectorOutput.detected_faces list is empty), then this shall be None.

fiqat.types.FeatureVector

Features usable for face recognition.

alias of np.ndarray

fiqat.types.FeatureVectorPair

FeatureVector pair that can be used to compute a ComparisonScore.

alias of tuple [ FeatureVector, FeatureVector ]

alias of tuple[ndarray, ndarray]

fiqat.types.ComparisonScore

The result of a FeatureVectorPair comparison.

alias of float

fiqat.types.SimilarityScore

A ComparisonScore that more specifically is a similarity score (ComparisonScoreType.SIMILARITY), meaning that higher values indicate higher similarity between the faces represented by the feature vectors.

alias of ComparisonScore

fiqat.types.QualityScore

A quality score produced by a MethodType.FACE_IMAGE_QUALITY_ASSESSMENT_ALGORITHM.

If the score itself is supposed to indicate the utility of the image for face recognition, then higher values should canonically indicate higher utility (i.e. higher should mean better).

alias of float

fiqat.types.InputImages

One or multiple InputImage items.

alias of Path | ndarray | Image | Iterable[Path | ndarray | Image]

fiqat.types.FaceDetectorOutputs

One or multiple FaceDetectorOutput items.

alias of FaceDetectorOutput | Iterable[FaceDetectorOutput]

fiqat.types.PrimaryFaceEstimates

One or multiple PrimaryFaceEstimate items.

alias of PrimaryFaceEstimate | Iterable[PrimaryFaceEstimate]

fiqat.types.TypedNpImages

One or multiple TypedNpImage items.

alias of TypedNpImage | Iterable[TypedNpImage]

fiqat.types.FeatureVectors

One or multiple FeatureVector items.

alias of ndarray | Iterable[ndarray]

fiqat.types.FeatureVectorPairs

One or multiple FeatureVectorPair items.

alias of tuple[ndarray, ndarray] | Iterable[tuple[ndarray, ndarray]]

fiqat.types.SimilarityScores

One or multiple SimilarityScore items.

alias of float | Iterable[float]

fiqat.types.ComparisonScores

One or multiple ComparisonScore items.

alias of float | Iterable[float]

fiqat.types.QualityScores

One or multiple QualityScore items.

alias of float | Iterable[float]

fiqat.types.namedtuple_types = (<class 'fiqat.types.DeviceConfig'>, <class 'fiqat.types.QualityScoreRange'>, <class 'fiqat.types.ComparisonScoreRange'>, <class 'fiqat.types.Cv2ColorTuple'>, <class 'fiqat.types.TypedNpImage'>, <class 'fiqat.types.ImageSize'>, <class 'fiqat.types.FaceRoi'>, <class 'fiqat.types.FacialLandmark'>, <class 'fiqat.types.PrimaryFaceEstimate'>)

All NamedTuple types in the fiqat.types module.

fiqat.types.enum_types = (<enum 'MethodType'>, <enum 'ComparisonScoreType'>, <enum 'ImageChannelType'>, <enum 'MethodRegistryStatus'>)

All enumeration types in the fiqat.types module.