iris.io package

Submodules

iris.io.class_configs module

class iris.io.class_configs.Algorithm(**kwargs: Any)

Bases: ABC

Base class of every node of the iris recognition pipeline.

class Parameters

Bases: ImmutableModel

Default parameters.

execute(*args: Any, **kwargs: Any) → Any

Execute method and wrapped with hooks if such are specified.

Returns:

Object specified by an interface.

Return type:

Any

run(*args: Any, **kwargs: Any) → Any

Implement method design pattern. Not overwritten by subclass will raise an error.

Raises:

NotImplementedError – Raised if subclass doesn’t implement run method.

Returns:

Return value by concrate implementation of the run method.

Return type:

Any

class iris.io.class_configs.ImmutableModel

Bases: BaseModel

Specifies configurations for validating classes which objects should be immutable.

class Config

Bases: object

Configuration options for classes which objects are meant to be immutable.

allow_mutation = False

arbitrary_types_allowed = True

extra = 'forbid'

smart_union = True

validate_all = True

static deserialize(self) → Any

Deserialize the object. By defaults, this method raises a RuntimeError to notify the user that the method wasn’t implemented.

Raises:

RuntimeError – Always.

serialize() → Any

Serialize the object. By defaults, this method raises a RuntimeError to notify the user that the method wasn’t implemented.

Raises:

RuntimeError – Always.

iris.io.dataclasses module

class iris.io.dataclasses.BoundingBox(*, x_min: float, y_min: float, x_max: float, y_max: float)

Bases: ImmutableModel

Data holder for eye’s bounding box.

static deserialize(data: Dict[str, float]) → BoundingBox

Deserialize BoundingBox object.

Parameters:

data (Dict[str, float]) – Serialized object to dict.

Returns:

Deserialized object.

Return type:

BoundingBox

serialize() → Dict[str, float]

Serialize BoundingBox object.

Returns:

Serialized object.

Return type:

Dict[str, float]

x_max: float

x_min: float

y_max: float

y_min: float

class iris.io.dataclasses.EyeCenters(*, pupil_x: float, pupil_y: float, iris_x: float, iris_y: float)

Bases: ImmutableModel

Data holder for eye’s centers.

property center_distance: float

Return distance between pupil and iris center.

Returns:

center distance.

Return type:

float

static deserialize(data: Dict[str, Tuple[float]]) → EyeCenters

Deserialize EyeCenters object.

Parameters:

data (Dict[str, Tuple[float]]) – Serialized object to dict.

Returns:

Deserialized object.

Return type:

EyeCenters

iris_x: float

iris_y: float

pupil_x: float

pupil_y: float

serialize() → Dict[str, Tuple[float]]

Serialize EyeCenters object.

Returns:

Serialized object.

Return type:

Dict[str, Tuple[float]]

class iris.io.dataclasses.EyeOcclusion(*, visible_fraction: ConstrainedFloatValue)

Bases: ImmutableModel

Data holder for the eye occlusion.

static deserialize(data: float) → EyeOcclusion

Deserialize EyeOcclusion object.

Parameters:

data (float) – Serialized object to float.

Returns:

Deserialized object.

Return type:

EyeOcclusion

serialize() → float

Serialize EyeOcclusion object.

Returns:

Serialized object.

Return type:

float

visible_fraction: float

class iris.io.dataclasses.EyeOrientation(*, angle: ConstrainedFloatValue)

Bases: ImmutableModel

Data holder for the eye orientation. The angle must be comprised between -pi/2 (included) and pi/2 (excluded).

angle: float

static deserialize(data: float) → EyeOrientation

Deserialize EyeOrientation object.

Parameters:

data (float) – Serialized object to float.

Returns:

Deserialized object.

Return type:

EyeOrientation

serialize() → float

Serialize EyeOrientation object.

Returns:

Serialized object.

Return type:

float

class iris.io.dataclasses.GeometryMask(*, pupil_mask: ndarray, iris_mask: ndarray, eyeball_mask: ndarray)

Bases: ImmutableModel

Data holder for the geometry raster.

static deserialize(data: Dict[str, Any]) → GeometryMask

Deserialize GeometryMask object.

Parameters:

data (Dict[str, Any]) – Serialized object to dict.

Returns:

Deserialized object.

Return type:

GeometryMask

eyeball_mask: ndarray

property filled_eyeball_mask: ndarray

Fill eyeball mask.

Returns:

Eyeball mask with filled iris/pupil “holes”.

Return type:

np.ndarray

property filled_iris_mask: ndarray

Fill iris mask.

Returns:

Iris mask with filled pupil “holes”.

Return type:

np.ndarray

iris_mask: ndarray

pupil_mask: ndarray

serialize() → Dict[str, Any]

Serialize GeometryMask object.

Returns:

Serialized object.

Return type:

Dict[str, Any]

class iris.io.dataclasses.GeometryPolygons(*, pupil_array: ndarray, iris_array: ndarray, eyeball_array: ndarray)

Bases: ImmutableModel

Data holder for the refined geometry polygons. Input np.ndarrays are mandatorily converted to np.float32 dtype for compatibility with some downstream tasks such as MomentsOfArea.

static deserialize(data: Dict[str, ndarray]) → GeometryPolygons

Deserialize GeometryPolygons object.

Parameters:

data (Dict[str, np.ndarray]) – Serialized object to dict.

Returns:

Deserialized object.

Return type:

GeometryPolygons

eyeball_array: ndarray

iris_array: ndarray

property iris_diameter: float

Return iris diameter.

Returns:

iris diameter.

Return type:

float

pupil_array: ndarray

property pupil_diameter: float

Return pupil diameter.

Returns:

pupil diameter.

Return type:

float

serialize() → Dict[str, ndarray]

Serialize GeometryPolygons object.

Returns:

Serialized object.

Return type:

Dict[str, np.ndarray]

class iris.io.dataclasses.IRImage(*, img_data: ndarray, eye_side: Literal['left', 'right'])

Bases: ImmutableModel

Data holder for input IR image.

static deserialize(data: Dict[str, Any]) → IRImage

Deserialize IRImage object.

Parameters:

data (Dict[str, Any]) – Serialized object to dict.

Returns:

Deserialized object.

Return type:

IRImage

eye_side: Literal['left', 'right']

property height: int

Return IR image’s height.

Returns:

image height.

Return type:

int

img_data: ndarray

serialize() → Dict[str, Any]

Serialize IRImage object.

Returns:

Serialized object.

Return type:

Dict[str, Any]

property width: int

Return IR image’s width.

Returns:

image width.

Return type:

int

class iris.io.dataclasses.IrisFilterResponse(*, iris_responses: List[ndarray], mask_responses: List[ndarray], iris_code_version: str)

Bases: ImmutableModel

Data holder for filter bank response with associated mask.

static deserialize(data: Dict[str, List[ndarray]]) → IrisFilterResponse

Deserialize IrisFilterResponse object.

Parameters:

data (Dict[str, List[np.ndarray]]) – Serialized object to dict.

Returns:

Deserialized object.

Return type:

IrisFilterResponse

iris_code_version: str

iris_responses: List[ndarray]

mask_responses: List[ndarray]

serialize() → Dict[str, List[ndarray]]

Serialize IrisFilterResponse object.

Returns:

Serialized object.

Return type:

Dict[str, List[np.ndarray]]

class iris.io.dataclasses.IrisTemplate(*, iris_codes: List[ndarray], mask_codes: List[ndarray], iris_code_version: str)

Bases: ImmutableModel

Data holder for final iris template with mask.

convert2old_format() → List[ndarray]

Convert an old tempalte format and the associated iris code version into an IrisTemplate object.

Returns:

Old engines pipeline object Tuple with (iris_codes, mask_codes).

Return type:

Tuple[np.ndarray, np.ndarray]

static convert_to_new_format(iris_codes: ndarray, mask_codes: ndarray, iris_code_version: str) → IrisTemplate

Convert an old template format and the associated iris code version into an IrisTemplate object.

Returns:

Old engines pipeline object Tuple with (iris_codes, mask_codes).

Return type:

Tuple[np.ndarray, np.ndarray]

static deserialize(serialized_template: dict[str, np.ndarray | str], array_shape: Tuple = (16, 256, 2, 2)) → IrisTemplate

Deserialize a dict with iris_codes, mask_codes and iris_code_version into an IrisTemplate object.

Parameters:

• serialized_template (dict[str, Union[np.ndarray, str]]) – Serialized object to dict.

• array_shape (Tuple, optional) – Shape of the iris code. Defaults to (16, 256, 2, 2).

Returns:

Serialized object.

Return type:

IrisTemplate

iris_code_version: str

iris_codes: List[ndarray]

mask_codes: List[ndarray]

static new_to_old_format(array: List[ndarray]) → ndarray

Convert new iris template format to old iris template format.

• New format is a list of arrays, each of shape (height_i, width_i, 2). The length of the list is nb_wavelets.

  This enable having different convolution layout for each wavelet.

• Old format is a numpy array of shape (height, width, nb_wavelets, 2)

Parameters:

codes (List[np.ndarray]) – New format iris/mask codes.

Returns:

Old format codes.

Return type:

np.ndarray

Raises:

ValueError – Raised if not all codes have the same shape. In this case, the IrisTemplate cannot be converted to the old format.

static old_to_new_format(array: ndarray) → List[ndarray]

Convert old iris template format to new iris template format.

• Old format is a list of arrays, each of shape (height_i, width_i, 2). The length of the list is nb_wavelets.

  This enable having different convolution layout for each wavelet.

• New format is a numpy array of shape (height, width, nb_wavelets, 2)

Parameters:

codes (List[np.ndarray]) – Old format iris/mask codes.

Returns:

New format codes.

Return type:

np.ndarray

serialize() → Dict[str, bytes]

Serialize IrisTemplate object.

Returns:

Serialized object.

Return type:

Dict[str, bytes]

class iris.io.dataclasses.Landmarks(*, pupil_landmarks: ndarray, iris_landmarks: ndarray, eyeball_landmarks: ndarray)

Bases: ImmutableModel

Data holder for eye’s landmarks.

static deserialize(data: Dict[str, List[float]]) → Landmarks

Deserialize Landmarks object.

Parameters:

data (Dict[str, List[float]]) – Serialized object to dict.

Returns:

Deserialized object.

Return type:

Landmarks

eyeball_landmarks: ndarray

iris_landmarks: ndarray

pupil_landmarks: ndarray

serialize() → Dict[str, List[float]]

Serialize Landmarks object.

Returns:

Serialized object.

Return type:

Dict[str, List[float]]

class iris.io.dataclasses.NoiseMask(*, mask: ndarray)

Bases: ImmutableModel

Data holder for the refined geometry masks.

static deserialize(data: Dict[str, ndarray]) → NoiseMask

Deserialize NoiseMask object.

Parameters:

data (Dict[str, np.ndarray]) – Serialized object to dict.

Returns:

Deserialized object.

Return type:

NoiseMask

mask: ndarray

serialize() → Dict[str, ndarray]

Serialize NoiseMask object.

Returns:

Serialized object.

Return type:

Dict[str, np.ndarray]

class iris.io.dataclasses.NormalizedIris(*, normalized_image: ndarray, normalized_mask: ndarray)

Bases: ImmutableModel

Data holder for the normalized iris images.

static deserialize(data: Dict[str, ndarray]) → NormalizedIris

Deserialize NormalizedIris object.

Parameters:

data (Dict[str, np.ndarray]) – Serialized object to dict.

Returns:

Deserialized object.

Return type:

NormalizedIris

normalized_image: ndarray

normalized_mask: ndarray

serialize() → Dict[str, ndarray]

Serialize NormalizedIris object.

Returns:

Serialized object.

Return type:

Dict[str, np.ndarray]

class iris.io.dataclasses.Offgaze(*, score: ConstrainedFloatValue)

Bases: ImmutableModel

Data holder for offgaze score.

static deserialize(data: float) → Offgaze

Deserialize Offgaze object.

Parameters:

data (float) – Serialized object to float.

Returns:

Deserialized object.

Return type:

Offgaze

score: float

serialize() → float

Serialize Offgaze object.

Returns:

Serialized object.

Return type:

float

class iris.io.dataclasses.PupilToIrisProperty(*, pupil_to_iris_diameter_ratio: ConstrainedFloatValue, pupil_to_iris_center_dist_ratio: ConstrainedFloatValue)

Bases: ImmutableModel

Data holder for pupil-ro-iris ratios.

static deserialize(data: Dict[str, float]) → PupilToIrisProperty

Deserialize PupilToIrisProperty object.

Parameters:

data (Dict[str, float]) – Serialized object to dict.

Returns:

Deserialized object.

Return type:

PupilToIrisProperty

pupil_to_iris_center_dist_ratio: float

pupil_to_iris_diameter_ratio: float

serialize() → Dict[str, float]

Serialize PupilToIrisProperty object.

Returns:

Serialized object.

Return type:

Dict[str, float]

class iris.io.dataclasses.SegmentationMap(*, predictions: ndarray, index2class: Dict[NonNegativeInt, str])

Bases: ImmutableModel

Data holder for the segmentation models predictions.

static deserialize(data: Dict[str, Any]) → SegmentationMap

Deserialize SegmentationMap object.

Parameters:

data (Dict[str, Any]) – Serialized object to dict.

Returns:

Deserialized object.

Return type:

SegmentationMap

property height: int

Return segmap’s height.

Returns:

segmap height.

Return type:

int

index2class: Dict[NonNegativeInt, str]

index_of(class_name: str) → int

Get class index based on its name.

Parameters:

class_name (str) – Class name

Raises:

ValueError – Index of a class

Returns:

Raised if class_name not found in index2class dictionary.

Return type:

int

property nb_classes: int

Return the number of classes of the segmentation map (i.e. nb channels).

Returns:

number of classes in the segmentation map.

Return type:

int

predictions: ndarray

serialize() → Dict[str, Any]

Serialize SegmentationMap object.

Returns:

Serialized object.

Return type:

Dict[str, Any]

property width: int

Return segmap’s width.

Returns:

segmap width.

Return type:

int

iris.io.errors module

exception iris.io.errors.BoundingBoxEstimationError

Bases: Exception

BoundingBoxEstimationError module Error class.

exception iris.io.errors.EncoderError

Bases: Exception

Encoder module Error class.

exception iris.io.errors.ExtrapolatedPolygonsInsideImageValidatorError

Bases: Exception

ExtrapolatedPolygonsInsideImageValidatorError error class.

exception iris.io.errors.EyeCentersEstimationError

Bases: Exception

EyeOrientationEstimation module Error class.

exception iris.io.errors.EyeCentersInsideImageValidatorError

Bases: Exception

EyeCentersInsideImageValidatorError error class.

exception iris.io.errors.EyeOrientationEstimationError

Bases: Exception

EyeOrientationEstimation module Error class.

exception iris.io.errors.GeometryEstimationError

Bases: Exception

GeometryEstimation module Error class.

exception iris.io.errors.GeometryRefinementError

Bases: Exception

GeometryRefinementError error class.

exception iris.io.errors.IRISPipelineError

Bases: Exception

IRIS Pipeline module Error class.

exception iris.io.errors.ImageFilterError

Bases: Exception

ImageFilter’s base and subclasses error class.

exception iris.io.errors.IsPupilInsideIrisValidatorError

Bases: Exception

IsPupilInsideIrisValidator error class.

exception iris.io.errors.LandmarkEstimationError

Bases: Exception

LandmarkEstimationError module Error class.

exception iris.io.errors.MatcherError

Bases: Exception

Matcher module Error class.

exception iris.io.errors.NormalizationError

Bases: Exception

Normalization module Error class.

exception iris.io.errors.OcclusionError

Bases: Exception

EyeOrientationEstimation module Error class.

exception iris.io.errors.OffgazeEstimationError

Bases: Exception

OffgazeEstimation module Error class.

exception iris.io.errors.ProbeSchemaError

Bases: Exception

ProbeSchema’s base and subclasses error class.

exception iris.io.errors.PupilIrisPropertyEstimationError

Bases: Exception

PupilIrisPropertyEstimation module Error class.

exception iris.io.errors.VectorizationError

Bases: Exception

Vectorization module Error class.

iris.io.validators module

iris.io.validators.are_all_positive(cls: type, v: Any, field: ModelField) → Any

Check that all values are positive.

Parameters:

• cls (type) – Class type.

• v (Any) – Value to check.

• field (fields.ModelField) – Field descriptor.

Raises:

ValueError – Raise if not all values in are positive.

Returns:

v sent for further processing.

Return type:

Any

iris.io.validators.are_all_shapes_equal(field1: str, field2: str) → Callable

Create a pydantic validator checking if two lists of array have the same shape per element.

This function creates a pydantic validator for two lists of np.ndarrays which checks if they have the same length, and if all of their element have the same shape one by one.

Parameters:

• field1 (str) – name of the first field

• field2 (str) – name of the first field

Returns:

the validator.

Return type:

Callable

iris.io.validators.are_lengths_equal(field1: str, field2: str) → Callable

Create a pydantic validator checking if the two fields have the same length.

Parameters:

• field1 (str) – name of the first field

• field2 (str) – name of the first field

Returns:

the validator.

Return type:

Callable

iris.io.validators.are_shapes_equal(field1: str, field2: str) → Callable

Create a pydantic validator checking if the two fields have the same shape.

Parameters:

• field1 (str) – name of the first field

• field2 (str) – name of the first field

Returns:

the validator.

Return type:

Callable

iris.io.validators.iris_code_version_check(cls: type, v: str, field: ModelField) → str

Check if the version provided in the input config matches the current iris.__version__.

iris.io.validators.is_array_n_dimensions(nb_dimensions: int) → Callable

Create a pydantic validator checking if an array is n-dimensional.

Parameters:

nb_dimensions (int) – number of dimensions the array must have

Returns:

the validator.

Return type:

Callable

iris.io.validators.is_binary(cls: type, v: ndarray, field: ModelField) → ndarray

Check if array has only boolean values, i.e. is binary.

Parameters:

• cls (type) – Class type.

• v (np.ndarray) – Value to check.

• field (fields.ModelField) – Field descriptor.

Raises:

ValueError – Exception raised if array doesn’t contain bool datatypes.

Returns:

v sent for further processing.

Return type:

np.ndarray

iris.io.validators.is_list_of_points(cls: type, v: ndarray, field: ModelField) → ndarray

Check if np.ndarray has shape (_, 2).

Parameters:

• cls (type) – Class type.

• v (np.ndarray) – Value to check.

• field (fields.ModelField) – Field descriptor.

Raises:

ValueError – Exception raised if array doesn’t contain 2D points.

Returns:

v sent for further processing.

Return type:

np.ndarray

iris.io.validators.is_not_empty(cls: type, v: List[Any], field: ModelField) → List[Any]

Check that both inputs are not empty.

Parameters:

• cls (type) – Class type.

• v (List[Any]) – Value to check.

• field (fields.ModelField) – Field descriptor.

Raises:

ValueError – Exception raised if list is empty.

Returns:

v sent for further processing.

Return type:

List[Any]

iris.io.validators.is_not_zero_sum(cls: type, v: Any, field: ModelField) → Any

Check that both inputs are not empty.

Parameters:

• cls (type) – Class type.

• v (Any) – Value to check.

• field (fields.ModelField) – Field descriptor.

Raises:

ValueError – Raised if v doesn’t sum to 0.

Returns:

v sent for further processing.

Return type:

Any

iris.io.validators.is_odd(cls: type, v: int, field: ModelField) → int

Check that kernel size are odd numbers.

Parameters:

• cls (type) – Class type.

• v (int) – Value to check.

• field (fields.ModelField) – Field descriptor.

Raises:

ValueError – Exception raised if number isn’t odd.

Returns:

v sent for further processing.

Return type:

int

iris.io.validators.is_uint8(cls: type, v: ndarray, field: ModelField) → ndarray

Check if np array contains only uint8 values.

iris.io.validators.is_valid_bbox(cls: type, values: Dict[str, float]) → Dict[str, float]

Check that the bounding box is valid.

iris.io.validators.to_dtype_float32(cls: type, v: ndarray, field: ModelField) → ndarray

Convert input np.ndarray to dtype np.float32.

Parameters:

• cls (type) – Class type.

• v (np.ndarray) – Value to convert

• field (fields.ModelField) – Field descriptor.

Returns:

v sent for further processing.

Return type:

np.ndarray

Module contents