iris.utils package

Submodules

iris.utils.base64_encoding module

iris.utils.base64_encoding.base64_decode_array(bytes_array: str, array_shape: Tuple[int, int, int, int] = (16, 256, 2, 2)) → ndarray[source]

Convert a packed base64 string to a numpy array.

Parameters:

  • bytes_array (bytes) – The packed base64 byte string.

  • shape (Tuple[int, int, int, int], optional) – The shape of the array. Defaults to (16, 256, 2, 2).

Returns:

The array.

Return type:

np.ndarray

iris.utils.base64_encoding.base64_decode_str(base64_str: str) → str[source]

Convert base64-encoded string to decoded string. Both input and output are string, but base64 encoded vs non-encoded.

Parameters:

base64_str (str) – The base64-encoded string

Returns:

the decoded string

Return type:

str

iris.utils.base64_encoding.base64_encode_array(array2encode: ndarray) → bytes[source]

Convert a numpy array to a packed base64 string.

Parameters:

array2encode (np.ndarray) – The array to convert.

Returns:

The packed base64 string.

Return type:

bytes

iris.utils.base64_encoding.base64_encode_str(input_str: str) → str[source]

Convert a string to base64 string. Both input and output are string, but base64 encoded vs non-encoded.

Parameters:

input_str (str) – The string to encode.

Returns:

the encoded base64 string.

Return type:

str

iris.utils.common module

iris.utils.common.contour_to_mask(vertices: ndarray, mask_shape: Tuple[int, int]) → ndarray[source]

Generate binary mask based on polygon’s vertices.

Parameters:

  • vertices (np.ndarray) – Vertices points array.

  • mask_shape (Tuple[int, int]) – Tuple with output mask dimension (weight, height).

Returns:

Binary mask.

Return type:

np.ndarray

iris.utils.math module

iris.utils.math.apply_weights_1d(scores_1d: ndarray, weights_1d: ndarray) → float[source]

Apply weights for score fusion.

Parameters:

  • scores_1d (np.ndarray) – scores to be fused.

  • weights_1d (np.ndarray) – weights.

Raises:

ValueError – if the input 1d arrays do not have the same length.

Returns:

fused score.

Return type:

float

iris.utils.math.area(array: ndarray, signed: bool = False) → float[source]

Shoelace formula for simple polygon area calculation.

WARNING: This formula only works for “simple polygons”, i.e planar polygon without self-intersection nor holes. These conditions are not checked within this function.

Parameters:

  • array (np.ndarray) – np array representing a polygon as a list of points, i.e. of shape (_, 2).

  • signed (bool) – If True, the area is signed, i.e. negative if the polygon is oriented clockwise.

Returns:

Polygon area

Return type:

float

Raises:

ValueError – if the input array does not have shape (_, 2)

References

[1] https://en.wikipedia.org/wiki/Shoelace_formula [2] https://stackoverflow.com/questions/24467972/calculate-area-of-polygon-given-x-y-coordinates

iris.utils.math.cartesian2polar(xs: ndarray, ys: ndarray, center_x: float, center_y: float) → Tuple[ndarray, ndarray][source]

Convert xs and ys cartesian coordinates to polar coordinates.

Parameters:

  • xs (np.ndarray) – x values.

  • ys (np.ndarray) – y values.

  • center_x (float) – center’s x.

  • center_y (float) – center’s y.

Returns:

Converted coordinates (rhos, phis).

Return type:

Tuple[np.ndarray, np.ndarray]

iris.utils.math.eccentricity(moments: Dict[str, float]) → float[source]

Compute the eccentricity of a contour or a binary image given its precomputed cv2 moments.

The eccentricity is a number in [0, 1] which caracterises the “roundness” or “linearity” of a shape. A perfect circle will have an eccentricity of 0, and an infinite line an eccentricity of 1. For ellipses, the eccentricity is calculated as \(\frac{\sqrt{a^2 - b^2}}{a^2}\) with a (resp. b) the semi-major (resp. -minor) axis of the ellipses.

For mu20 + mu02 == 0, i.e. perfect line, the max theoretical value (1.0) is returned

Parameters:

moments (Dict[str, float]) – cv2.moments of desired the binary image or contour.

Returns:

the eccentricity of the contour or binary map.

Return type:

eccentricity (float)

Reference:

[1] https://t1.daumcdn.net/cfile/tistory/15425F4150F4EBFC19

iris.utils.math.estimate_diameter(polygon: ndarray) → float[source]

Estimates the diameter of an arbitrary arc by evaluating the maximum distance between any two points on the arc.

Parameters:

polygon (np.ndarray) – Polygon points.

Returns:

Estimated diameter length.

Return type:

float

Reference:

[1] https://sparrow.dev/pairwise-distance-in-numpy/

iris.utils.math.orientation(moments: Dict[str, float]) → float[source]

Compute the main orientation of a contour or a binary image given its precomputed cv2 moments.

Parameters:

moments (Dict[str, float]) – cv2.moments of desired the binary image or contour.

Returns:

Main orientation of the shape. The orientation is a float in [-pi/2, pi/2[ representing the signed angle from the x axis.

Return type:

float

iris.utils.math.polar2cartesian(rhos: ndarray, phis: ndarray, center_x: float, center_y: float) → Tuple[ndarray, ndarray][source]

Convert polar coordinates to cartesian coordinates.

Parameters:

  • rho (np.ndarray) – rho values.

  • phi (np.ndarray) – phi values.

  • center_x (float) – center’s x.

  • center_y (float) – center’s y.

Returns:

Converted coordinates (xs, ys).

Return type:

Tuple[np.ndarray, np.ndarray]

iris.utils.math.polygon_length(polygon: ndarray, max_point_distance: int = 20) → float[source]

Compute the length of a polygon represented as a (_, 2)-dimensionnal numpy array.

One polygon can include several disjoint arcs, which should be identified as separate so that the distance between them is not counted. If a polygon is made of two small arc separated by a large distance, then the large distance between the two arcs will not be discounted in the polygon’s length

WARNING: The input polygon is assumed to be non-looped, i.e. if the first and last point are not equal, which is the case for all ou GeometryPolygons. The last implicit segment looping back from the last to the first point is therefore not included in the computed polygon length.

Parameters:

  • polygon (np.ndarray) – (_, 2) - shaped numpy array representing a polygon.

  • max_point_distance (int) – Maximum distance between two points for them to be considered part of the same arc.

Returns:

length of the polygon, in pixels.

Return type:

float

iris.utils.visualisation module

class iris.utils.visualisation.IRISVisualizer[source]

Bases: object

IRISPipeline outputs visualizer.

plot_all_geometry(ir_image: IRImage | Dict[str, Any], geometry_polygons: GeometryPolygons | Dict[str, ndarray], eye_orientation: EyeOrientation | float, eye_center: EyeCenters | Dict[str, Tuple[float]]) → Tuple[Figure, Axes | ndarray][source]

Visualises all major geometry-related objects produced at an IR image level.

This function displays the source IR Image, the produced GeometryPolygons, the eye orientation, and the pupil and iris centers.

Parameters:

  • ir_image (iris_dc.IRImage) – source IR Image

  • geometry_polygons (Union[iris_dc.GeometryPolygons, Dict[str, np.ndarray]]) – geometry polygons from any stage of the pipeline

  • eye_orientation (Union[iris_dc.EyeOrientation, float]) – eye orientation to visualise

  • eye_center (Union[iris_dc.EyeCenters, Dict[str, Tuple[float]]]) – eye centers to visualise

Returns:

Figure and axes.

Return type:

Canvas

plot_eye_centers(eye_centers: EyeCenters | Dict[str, Tuple[float]], ir_image: IRImage | Dict[str, Any] | None = None, ax: Axes | None = None) → Tuple[Figure, Axes | ndarray][source]

Visualise an IRIS EyeCenters object.

Parameters:

  • eye_center (Union[iris_dc.EyeCenters, Dict[str, Tuple[float]]]) – Eye centers to visualise

  • ir_image (Optional[Union[iris_dc.IRImage, Dict[str, Any]]], optional) – Optional IRImage to lay over in transparency. Defaults to None.

  • ax (Optional[matplotlib.axes._axes.Axes]) – ax to plot the figure at. Defaults to None.

Returns:

Figure and axes.

Return type:

Canvas

plot_eye_orientation(eye_orientation: EyeOrientation | float, eye_centers: EyeCenters | Dict[str, Tuple[float]], ir_image: IRImage | Dict[str, Any] | None = None, ax: Axes | None = None) → Tuple[Figure, Axes | ndarray][source]

Visualise an IRIS EyeOrientation object. Require an EyeCenters.

Parameters:

  • eye_orientation (Union[iris_dc.EyeOrientation, float]) – EyeOrientation to visualise

  • eye_centers (Union[iris_dc.EyeCenters, Dict[str, Tuple[float]]]) – EyeCenters, from which the origin of the displayed vector is inferred.

  • ir_image (Optional[Union[iris_dc.IRImage, Dict[str, Any]]], optional) – optional IRImage to lay over in transparency. Defaults to None.

  • ax (Optional[matplotlib.axes._axes.Axes]) – ax to plot the figure at. Defaults to None.

Returns:

output figure and axes

Return type:

Canvas

plot_geometry_mask(geometry_mask: GeometryMask | Dict[str, Any], ir_image: IRImage | Dict[str, Any] | None = None, ax: Axes | None = None) → Tuple[Figure, Axes | ndarray][source]

Visualize an IRIS GeometryMask objet.

Parameters:

  • geometry_mask (Union[iris_dc.GeometryMask, Dict[str, Any]]) – Geometry mask.

  • ir_image (Optional[Union[iris_dc.IRImage, Dict[str, Any]]], optional) – Optional IRImage to lay over in transparency. Defaults to None.

  • ax (Optional[matplotlib.axes._axes.Axes], optional) – ax to plot the figure at. Defaults to None.

Returns:

Figure and axes.

Return type:

Canvas

plot_geometry_polygons(geometry_polygons: GeometryPolygons | Dict[str, ndarray], ir_image: IRImage | Dict[str, Any] | None = None, plot_kwargs: Dict[str, Any] | None = None, scatter_kwargs: Dict[str, Any] | None = None, ax: Axes | None = None) → Tuple[Figure, Axes | ndarray][source]

Visualise an IRIS GeometryPolygons object.

Parameters:

  • geometry_polygons (Union[iris_dc.GeometryPolygons, Dict[str, np.ndarray]]) – Geometry polygons to visualise

  • ir_image (Optional[Union[iris_dc.IRImage, Dict[str, Any]]], optional) – Optional IRImage to lay over in transparency. Defaults to None.

  • plot_kwargs (Optional[Dict[str, Any]], optional) – Kwargs of a plot function. Defaults to None.

  • scatter_kwargs (Optional[Dict[str, Any]], optional) – Kwargs of a scatter function. Defaults to None.

  • ax (Optional[matplotlib.axes._axes.Axes]) – ax to plot the figure at. Defaults to None.

Returns:

Figure and axes.

Return type:

Canvas

plot_ir_image(ir_image: IRImage | Dict[str, Any], ax: Axes | None = None) → Tuple[Figure, Axes | ndarray][source]

Visualise an IRIS IRImage.

Parameters:

  • ir_image (Union[iris_dc.IRImage, Dict[str, Any]]) – input image of iris’ IRImage type

  • ax (Optional[matplotlib.axes._axes.Axes]) – ax to plot the figure at. Defaults to None.

Returns:

Figure and axes.

Return type:

Canvas

plot_ir_image_with_landmarks(ir_image: IRImage | Dict[str, Any], landmarks: Landmarks | Dict[str, List[float]], ax: Axes | None = None) → Tuple[Figure, Axes | ndarray][source]

Plot landmarks together with IR image.

Parameters:

  • ir_image (Union[iris_dc.IRImage, Dict[str, Any]]) – IR image.

  • landmarks (Union[iris_dc.Landmarks, Dict[str, List[float]]]) – Landmarks.

  • ax (Optional[matplotlib.axes._axes.Axes], optional) – ax to plot the figure at. Defaults to None.

Returns:

Figure and axes.

Return type:

Canvas

plot_iris_filter_response(iris_filter_response: IrisFilterResponse | Dict[str, List[ndarray]], space: Literal['cartesian', 'polar'] = 'cartesian', plot_mask: bool = True, mask_threshold: float = 0.9, vlim: float = 0.001, ax: Axes | None = None) → Tuple[Figure, Axes | ndarray][source]

Visualise an IRIS IrisFilterResponse object.

Parameters:

  • iris_filter_response (Union[iris_dc.IrisFilterResponse, Dict[str, List[np.ndarray]]]) – iris filter response to visualise.

  • space (Literal["cartesian", "polar"], optional) – Wether to plot the response in cartesian or polar coordinates. Defaults to cartesian.

  • plot_mask (bool, optional) – Wether to overlay the mask response in transparency. Defaults to True.

  • mask_threshold (float, optional) – Wether to overlay the mask in transparency. Defaults to 0.9.

  • vlim (float, optional) – The maximal value displayed in real, imaginary and amplitude graphs. Defaults to 1e-3

  • ax (Optional[matplotlib.axes._axes.Axes]) – ax to plot the figure at. Defaults to None.

Returns:

Figure and axes.

Return type:

Canvas

plot_iris_template(iris_template: IrisTemplate | Dict[str, ndarray], plot_mask: bool = True, ax: Axes | None = None) → Tuple[Figure, Axes | ndarray][source]

Visualise an IRIS IrisTemplate object.

Parameters:

  • iris_template (Union[iris_dc.IrisTemplate, Dict[str, np.ndarray]]) – iris template to visualise

  • plot_mask (bool, optional) – Wether to overlay the mask in transparency. Defaults to True.

  • ax (Optional[matplotlib.axes._axes.Axes]) – ax to plot the figure at. Defaults to None.

Returns:

Figure and axes.

Return type:

Canvas

plot_iris_template_and_normalized_iris(iris_template: IrisTemplate, normalized_iris: NormalizedIris | Dict[str, ndarray], plot_mask: bool = True, linewidth: float = 0.5, fill_alpha: float = 0.05, ax: Axes | None = None) → Tuple[Figure, Axes | ndarray][source]

Visualises a normalised iris image and its associated iris template.

Parameters:

  • iris_template (iris_dc.IrisTemplate) – iris template to visualise

  • normalized_iris (Union[iris_dc.NormalizedIris, Dict[str, np.ndarray]]) – normalised iris to visualise

  • plot_mask (bool, optional) – Wether to overlay the mask in transparency. Defaults to True.

  • linewidth (float, optional) – line width of the iris template. Defaults to 0.5.

  • fill_alpha (float, optional) – transparency of the overlaid iris template. Defaults to 0.05.

  • ax (Optional[matplotlib.axes._axes.Axes]) – ax to plot the figure at. Defaults to None.

Returns:

Figure and axes.

Return type:

Canvas

plot_noise_mask(noise_mask: NoiseMask | Dict[str, ndarray], ir_image: IRImage | Dict[str, Any] | None = None, ax: Axes | None = None) → Tuple[Figure, Axes | ndarray][source]

Visualize an IRIS NoiseMask objet.

Parameters:

  • noise_mask (Union[iris_dc.NoiseMask, Dict[str, np.ndarray]]) – Noise mask.

  • ir_image (Optional[Union[iris_dc.IRImage, Dict[str, Any]]], optional) – Optional IRImage to lay over in transparency. Defaults to None.

  • ax (Optional[matplotlib.axes._axes.Axes], optional) – ax to plot the figure at. Defaults to None.

Returns:

Figure and axes.

Return type:

Canvas

plot_normalized_iris(normalized_iris: NormalizedIris | Dict[str, ndarray], plot_mask: bool = True, stretch_hist: bool = True, exposure_factor: float = 1.0, ax: Axes | None = None) → Tuple[Figure, Axes | ndarray][source]

Visualise an IRIS NormalizedIris object.

Parameters:

  • normalized_iris (Union[iris_dc.NormalizedIris, Dict[str, np.ndarray]]) – Normalized iris image

  • plot_mask (bool, optional) – Wether to overlay the normalised mask in transparency. Defaults to True.

  • stretch_hist (bool, optional) – Wether to ignore masked out pixels in the image histogram. Useful for darker images. Defaults to True.

  • exposure_factor (float, optional) – Multiplicative factor to brighten the image. Defaults to 1.0.

  • ax (Optional[matplotlib.axes._axes.Axes]) – ax to plot the figure at. Defaults to None.

Returns:

Figure and axes.

Return type:

Canvas

plot_segmentation_map(segmap: SegmentationMap | Dict[str, Any], ir_image: IRImage | Dict[str, Any] | None = None, ax: Axes | None = None) → Tuple[Figure, Axes | ndarray][source]

Plot segmentation maps.

Parameters:

  • segmap (Union[iris_dc.SegmentationMap, Dict[str, Any]]) – Segmentation maps.

  • ir_image (Optional[Union[iris_dc.IRImage, Dict[str, Any]]], optional) – IR image. Defaults to None.

  • ax (Optional[matplotlib.axes._axes.Axes], optional) – ax to plot the figure at. Defaults to None.

Returns:

Figure and axes.

Return type:

Canvas

Module contents