iris.nodes.eye_properties_estimation package

Submodules

iris.nodes.eye_properties_estimation.bisectors_method module

class iris.nodes.eye_properties_estimation.bisectors_method.BisectorsMethod(num_bisectors: int = 100, min_distance_between_sector_points: float = 0.75, max_iterations: int = 50)

Bases: Algorithm

Implementation of eye’s center estimation algorithm using bisectors method for finding a circle center.

This algorithm samples a given number of bisectors from the pupil and iris polygons, and averages their intersection to produce the polygon center. This method is robust against noise in the polygons, making it a good choice for non-perfect shapes. It is also robust to polygons missing parts of the circle arc, making it a good choice for partially-occluded shapes.

LIMITATIONS: The iris and pupil can be approximated to circles, when the user is properly gazing at the camera. This requires that the cases of off-gaze have already been filtered out.

class Parameters(*, num_bisectors: ConstrainedIntValue, min_distance_between_sector_points: ConstrainedFloatValue, max_iterations: ConstrainedIntValue)

Bases: Parameters

Default Parameters for BisectorsMethod algorithm.

max_iterations: int

min_distance_between_sector_points: float

num_bisectors: int

run(geometries: GeometryPolygons) → EyeCenters

Estimate eye’s iris and pupil centers.

Parameters:

geometries (GeometryPolygons) – Geometry polygons.

Returns:

Eye’s centers object.

Return type:

EyeCenters

iris.nodes.eye_properties_estimation.eccentricity_offgaze_estimation module

class iris.nodes.eye_properties_estimation.eccentricity_offgaze_estimation.EccentricityOffgazeEstimation(assembling_method: Literal['min', 'max', 'mean', 'only_pupil', 'only_iris'] = 'min', eccentricity_method: Literal['moments', 'ellipse_fit', 'ellipse_fit_direct', 'ellipse_fit_ams'] = 'moments', callbacks: List[Callback] = [])

Bases: Algorithm

Determines an off-gaze score by assembling the eccentricity of the iris and pupil polygons.

The goal of this algorithm is to attribute an offgaze score to the GeometryPolygons associated with an IR image.

The user’s iris is approximated to a circle. If the plane containing that circle (i.e. the iris) is orthogonal to the direction of the camera (i.e. the user looks straight at the camera), then the iris will appear as circular as possible. If the user doesn’t look straight at the camera, the circle will appear tilted because of the perspective. The iris (and pupil) circle will then tend towards an ellipsis more than a circle.

This shift in general shape can be measured through the eccentricity of the iris (resp. pupil), a measure using moments of the shape, between 0 (perfect circle) and 1 (perfect line)

The eccentricity of a shape can be determined in two ways:

• moments: the moments of the shape are determined, from which we can infer its eccentricity

• fit_ellipse: an ellipse is fitted to the shape, and the ellipse’s eccentricity is returned

• fit_ellipse_direct: TBFU

• fit_ellipse_ams: TBFU

The eccentricity of the iris and pupil can then be assembled in various ways:

• min: the minimum between pupil and iris eccentricity

• max: the maximum between pupil and iris eccentricity

• mean: the average between pupil and iris eccentricity

• only_pupil: pupil eccentricity

• only_iris: iris eccentricity

LIMITATIONS:

It is known that irises (and pupil even more) are not perfectly circular shapes. This means that non-offgaze might have significantly non-zero values. Also, it is possible that an offgaze might have a pupil and / or iris very circular.

class Parameters(*, assembling_method: Literal['min', 'max', 'mean', 'only_pupil', 'only_iris'], eccentricity_method: Literal['moments', 'ellipse_fit', 'ellipse_fit_direct', 'ellipse_fit_ams'])

Bases: Parameters

Parameters class for EccentricityOffgazeEstimation objects.

assembling_method: Literal['min', 'max', 'mean', 'only_pupil', 'only_iris']

eccentricity_method: Literal['moments', 'ellipse_fit', 'ellipse_fit_direct', 'ellipse_fit_ams']

assembling_method2function_mapping = {'max': <built-in function max>, 'mean': <function EccentricityOffgazeEstimation.<lambda>>, 'min': <built-in function min>, 'only_iris': <function EccentricityOffgazeEstimation.<lambda>>, 'only_pupil': <function EccentricityOffgazeEstimation.<lambda>>}

eccentricity_method2function_mapping = {'ellipse_fit': <function get_eccentricity_through_ellipse_fit>, 'ellipse_fit_ams': <function get_eccentricity_through_ellipse_fit_ams>, 'ellipse_fit_direct': <function get_eccentricity_through_ellipse_fit_direct>, 'moments': <function get_eccentricity_through_moments>}

run(geometries: GeometryPolygons) → Offgaze

Calculate offgaze estimation.

Parameters:

geometries (GeometryPolygons) – polygons used for offgaze estimation.

Returns:

offgaze object.

Return type:

Offgaze

iris.nodes.eye_properties_estimation.eccentricity_offgaze_estimation.get_eccentricity_through_ellipse_fit(shape_array: ndarray) → float

Determine the eccentricity of the shape by fitting an ellipse (default method).

Parameters:

shape_array (np.ndarray) – Shape array.

Returns:

Computed eccentricity.

Return type:

float

iris.nodes.eye_properties_estimation.eccentricity_offgaze_estimation.get_eccentricity_through_ellipse_fit_ams(shape_array: ndarray) → float

Determine the eccentricity of the shape by fitting an ellipse (AMS method).

Parameters:

shape_array (np.ndarray) – Shape array.

Returns:

Computed eccentricity.

Return type:

float

iris.nodes.eye_properties_estimation.eccentricity_offgaze_estimation.get_eccentricity_through_ellipse_fit_direct(shape_array: ndarray) → float

Determine the eccentricity of the shape by fitting an ellipse (DIRECT method).

Parameters:

shape_array (np.ndarray) – Shape array.

Returns:

Computed eccentricity.

Return type:

float

iris.nodes.eye_properties_estimation.eccentricity_offgaze_estimation.get_eccentricity_through_moments(shape_array: ndarray) → float

Determine the eccentricity of the shape through its second order image moments.

Parameters:

shape_array (np.ndarray) – Shape array.

Returns:

Computed eccentricity.

Return type:

float

iris.nodes.eye_properties_estimation.iris_bbox_calculator module

class iris.nodes.eye_properties_estimation.iris_bbox_calculator.IrisBBoxCalculator(buffer: int | float | Tuple[Number, Number] = 0, crop: bool = False)

Bases: Algorithm

Calculate the smallest bounding box around the iris polygon, cropped or not, padded or not.

class Parameters(*, buffer: int | float | Tuple[Number, Number], crop: bool)

Bases: Parameters

Parameters of the iris bounding box calculator.

buffer: int | float | Tuple[Number, Number]

crop: bool

run(ir_image: IRImage, geometry_polygons: GeometryPolygons) → BoundingBox

Compute the bounding box around the iris with an additional buffer. Works best on extrapolated polygons.

The buffer’s behaviour is explained in the constructor’s docstring. The bounding box will be cropped to the shape of the input IR Image.

Parameters:

• ir_image (IRImage) – IR image.

• geometry_polygons (GeometryPolygons) – polygons, from which the iris polygon (respectively the image shape) used to compute the bounding box (resp. crop the bounding box).

Returns:

Estimated iris bounding box.

Return type:

BoundingBox

iris.nodes.eye_properties_estimation.moment_of_area module

class iris.nodes.eye_properties_estimation.moment_of_area.MomentOfArea(eccentricity_threshold: float = 0.1)

Bases: Algorithm

Estimate the eye orientation using the second order moments of the eyeball polygon.

The eye orientation refers to the horizontal direction of the eye. It comes useful for determining the partial eye occlusion (e.g. occlusion at the horizontal middle third of the iris).

References

[1] https://t1.daumcdn.net/cfile/tistory/15425F4150F4EBFC19 [2] https://en.wikipedia.org/wiki/Image_moment

class Parameters(*, eccentricity_threshold: ConstrainedFloatValue)

Bases: Parameters

MomentOfArea parameters.

eccentricity_threshold: float in [0, 1].

The threshold below which a shape is considered not linear enough to reliably estimate its orientation.

eccentricity_threshold: float

run(geometries: GeometryPolygons) → EyeOrientation

Compute the eye orientation using the second order moments or the eyeball.

WARNING: cv2.moments MUST only receive np.float32 arrays. Otherwise, the array will be interpreted as a sparse matrix instead of a list of points. See https://github.com/opencv/opencv/issues/6643#issuecomment-224204774.

Parameters:

geometries (GeometryPolygons) – segmentation map used for eye orientation estimation.

Raises:

EyeOrientationEstimationError if the eyeball's eccentricity is below eccentricity_threshold i.e. if the eyeball shape is not circular enough to reliably estimate the orientation. –

Returns:

eye orientation object.

Return type:

EyeOrientation

iris.nodes.eye_properties_estimation.occlusion_calculator module

class iris.nodes.eye_properties_estimation.occlusion_calculator.OcclusionCalculator(quantile_angle: float, callbacks: List[Callback] = [])

Bases: Algorithm

Calculate the eye occlusion value.

This algorithm computes the fraction of visible iris in an image based on extrapolated polygons and the various noise masks. For an occlusion of 0, the iris is completely occluded. For an occlusion of 1, the iris is completely visible For historical reasons, this remained called “Occlusion”, while it more precisely refers to the “Opening” of the eye.

The parameter quantile_angle refers to the zone of the iris to consider for the occlusion computation. This is because the middle horizontal third of the iris is usually more useful, since less likely to be occluded by the eyelids. For a quantile_angle of 90º, the entire iris will be considered. For a quantile_angle of 30º, the horizontal middle third of the iris will be considered. For a quantile_angle of 0º, nothing will be considered (limit value).

class Parameters(*, quantile_angle: ConstrainedFloatValue)

Bases: Parameters

Default OcclusionCalculator parameters.

quantile_angle: float

run(extrapolated_polygons: GeometryPolygons, noise_mask: NoiseMask, eye_orientation: EyeOrientation, eye_centers: EyeCenters) → EyeOcclusion

Compute the iris visible fraction.

Parameters:

• extrapolated_polygons (GeometryPolygons) – Extrapolated polygons contours.

• noise_mask (NoiseMask) – Noise mask.

• eye_orientation (EyeOrientation) – Eye orientation angle.

• eye_centers (EyeCenters) – Eye centers.

Returns:

Visible iris fraction.

Return type:

EyeOcclusion

iris.nodes.eye_properties_estimation.pupil_iris_property_calculator module

class iris.nodes.eye_properties_estimation.pupil_iris_property_calculator.PupilIrisPropertyCalculator(min_pupil_diameter: float = 1.0, min_iris_diameter: float = 150.0, callbacks: List[Callback] = [])

Bases: Algorithm

Computes pupil-to-iris properties.

Algorithm steps:

1. Calculate pupil diameter to iris diameter ratio, i.e. pupil dilation.

2. Calculate the ratio of the pupil center to iris center distance over the iris diameter.

class Parameters(*, min_pupil_diameter: ConstrainedFloatValue, min_iris_diameter: ConstrainedFloatValue)

Bases: Parameters

PupilIrisPropertyCalculator parameters.

min_pupil_diameter (float): threshold of pupil diameter, below which the pupil is too small. min_pupil_diameter should be higher than 0. min_iris_diameter (float): threshold of iris diameter, below which the iris is too small. min_iris_diameter should be higher than 0.

min_iris_diameter: float

min_pupil_diameter: float

run(geometries: GeometryPolygons, eye_centers: EyeCenters) → PupilToIrisProperty

Calculate pupil-to-iris property.

Parameters:

• geometries (GeometryPolygons) – polygons used for calculating pupil-ro-iris property.

• eye_centers (EyeCenters) – eye centers used for calculating pupil-ro-iris property.

Raises:

PupilIrisPropertyEstimationError – Raised if 1) the pupil or iris diameter is too small, 2) pupil diameter is larger than or equal to iris diameter, 3) pupil center is outside iris.

Returns:

pupil-ro-iris property object.

Return type:

PupilToIrisProperty

Module contents