open-iris v1.1.0

[wiktorlazarski]

open-iris v1.1.0

PR description

Major

Added

• (Model Cards updates and new LinearNormalization algorithm #19) New LinearNormalization normalisation algorithm. This normalisation algorithm mimics PerspectiveNormalization and is based on the NearestNeighbor extrapolation, instead of Bilinear. This yields a ~20x speedup and remove a major bottleneck on the pipeline. The grid points are sampled linearly, unlike NonLinearNormalization which does so in a non-linear manner depending on the pupil-to-iris ratio.
• (Model Cards updates and new LinearNormalization algorithm #19) Quality filters are activated by default. Community members surfaced that performances on the default configuration were sometimes sub-par due to a low filtering of bad quality images. We decided to enable the quality filters by default, and as usual let users the possibility to remove them by changing the configuration. These filters are conservative and only reject the worst iris images, users are encouraged to fine-tune them for their use case. The default values are:
  • EyeCentersInsideImageValidator
    • min_distance_to_border: 0.0: images where the pupil enters are not strictly included in the pupil are filtered out. This only happens in the rare case of segmentation failure
  • PupilIrisPropertyCalculator
    • min_iris_diameter: 50: images where the iris diameter is lesser than 50 px are filtered out
  • Pupil2IrisPropertyValidator
  • min_allowed_diameter_ratio: 0.1: Images where the pupil diameter is lesser than 10% of the iris diameter are filtered out.
  • max_allowed_diameter_ratio: 0.7: Images where the pupil diameter is greater than 70% of the iris diameter are filtered out
  • max_allowed_center_dist_ratio: 0.9: Images where the pupil center is too far from the iris center (i.e. the pupil center to iris center distance is greater the 90% of the iris radius)
  • OffgazeValidator
    • max_allowed_offgaze: 0.8: images with an offgaze score above 0.8 are filtered out
  • OcclusionValidator
    • min_allowed_occlusion: 0.25: images where less than 25% of the iris texture is visible are filtered out
  • IsMaskTooSmallValidator:
    • min_maskcodes_size: 4096: iris codes with more than 4096 px masked out (i.e. 50%) are filtered out
• (open-iris v1.1.0 #27) Dataclasses additions:
  • Add an attribute iris_code_version to the dataclasses IrisFilterResponse and IrisTemplate.
  • Add serialisation and deserialisation to/from base64 encoding to the IrisTemplate class.
  • Add conversion to/from previous iris template format as class functions to IrisTemplate
• (open-iris v1.1.0 #27) Base64 encoding. On the Orb, communication happens through base64-encoded strings. The configuration received by open-iris is base64-encoded, which requires the capacity to decode and encode string on this format. These functions live in iris.utils.base64_encoding.

Modified

• (Simplify IRISPipeline output. #12) iris.IRISPipeline output has been simplified. The output structure remains the same (a dictionary). The value of iris_template is now an iris.IrisTemplate object compatible with downstream uses: matching, visualisations, etc. Users will not have to deserialise the object manually and will be able to use iris end-to-end without intermediary manipulations.

Minor

Added

• (Matching entities tutorial. #22) Added tutorial on how to match iris codes from iris images.

Modified

• (Yi update performance card #4) Add performance benchmark with other open-source software: end-to-end pipeline performance comparison with commercial iris scanners and with the HDBIF method on the dataset ICE2005
• (Add citation to README.md. #11) (Update Contact section in README #13) Update README
• (Update Code of Conduct #14) Update Code of Conduct
• (Bugfix/callbacks #18) Add callbacks arg in several nodes init
• (Add unit test for to_uint8 #25) iris.NormalizedIris.normalized_image is now of data type np.uint8
• (open-iris v1.1.0 #27) Downgrade opencv version from opencv-python==4.8.1.78 to opencv-python==4.7.0.68, for Orb compatibility.
• (open-iris v1.1.0 #27) iris.IRISPipeline.load_from_config_map is deprecated, in favour of iris.IRISPipeline.load_from_config. Instead of taking a dictionary mapping iris version with base64-encoded config, this load_from_config directly takes a base64-encoded config and instantiate an IRISPipeline object with this config
• (open-iris v1.1.0 #27) iris.utils.math.area takes an additional optional parameter, signed: bool, which if True, makes the function return signed area.

Fixed

• (Update README.md #5) (Fix readme typo #6) (fix typos in all documents #7) (fix typos in python files #8) Various typos
• (Model Cards updates and new LinearNormalization algorithm #19) Explicitly raise error instead of crashing when polygons do not have enough edges to be processed properly in ContourPointNoiseEyeballDistanceFilter and Smoothing
• (Disable hf_transfer usage when downloading semantic segmentation model. #20) Disable hf_transfer Hugging Face feature when downloading the semantic segmentation model weights. This prevents crashes when loading the model on certain systems.
• (Add unit test for to_uint8 #25) Fixed bug where the normalised image texture of an iris cropping out of the bottom left corner of the image would loop back to the bottom right corner image data. Now, normalised image texture corresponding to iris region cropped out of the image are black (0-valued pixel)
• (open-iris v1.1.0 #27) Fixed bug where the occlusion value did not take into account the areas of the iris cropped out of the input image. Now, the occlusion value is the ratio of areas of the visible iris region (excluding cropped out, masked out, covered by the eyelid, covered by eyelashes, etc.) and of the entire extrapolated iris (including cropped out of frame)

Type

• Feature
• Refactoring
• Bugfix

Checklist

• I've made sure that my code works as expected by writing unit tests.
• I've checked if my code doesn't generate warnings or errors.
• I've performed a self-review of my code.
• I've made sure that my code follows the style guidelines of the project.
• I've commented hard-to-understand parts of my code.
• I've made appropriate changes in the documentation.

[TanguyJeanneau]

Looks good to me ! 🪞🥓