Yichen1 ai 5172 refactor hd matching

docs/source/examples/matching_entities.rst

@@ -41,14 +41,18 @@ Create a ``HammingDistanceMatcher`` matcher object.
     def __init__(
         self,
         rotation_shift: int = 15,
-        nm_dist: Optional[confloat(ge=0, le=1, strict=True)] = None,
+        normalise: bool = True,
+        nm_dist: Optional[confloat(ge=0, le=1, strict=True)] = 0.45,
+        separate_half_matching: bool = True,
         weights: Optional[List[np.ndarray]] = None,
     ) -> None:
         """Assign parameters.
 
-        Args:
-            rotation_shift (int): rotations allowed in matching, converted to shifts in columns. Defaults to 15.
-            nm_dist (Optional[confloat(ge=0, le = 1, strict=True)]): nonmatch distance used for normalized HD. Optional paremeter for normalized HD. Defaults to None.
+       Args:
+            rotation_shift (int): rotations allowed in matching, experessed in iris code columns. Defaults to 15.
+            normalise (bool = False): Flag to normalize HD. Defaults to True.
+            nm_dist (Optional[confloat(ge=0, le = 1, strict=True)]): nonmatch distance used for normalized HD. Optional paremeter for normalized HD. Defaults to 0.45.
+            separate_half_matching (bool): separate the upper and lower halves for matching. Defaults to True.
             weights (Optional[List[np.ndarray]]): list of weights table. Optional paremeter for weighted HD. Defaults to None.
         """
 

src/iris/nodes/matcher/hamming_distance_matcher.py

@@ -1,11 +1,11 @@
-from typing import List, Literal, Optional
+from typing import List, Optional
 
 import numpy as np
 from pydantic import confloat
 
 from iris.io.dataclasses import IrisTemplate
-from iris.nodes.matcher.utils import hamming_distance
 from iris.nodes.matcher.hamming_distance_matcher_interface import Matcher
+from iris.nodes.matcher.utils import hamming_distance
 
 
 class HammingDistanceMatcher(Matcher):
@@ -26,28 +26,34 @@ class Parameters(Matcher.Parameters):
 
         normalise: bool
         nm_dist: confloat(ge=0, le=1, strict=True)
-        nm_type: Literal["linear", "sqrt"]
+        separate_half_matching: bool
         weights: Optional[List[np.ndarray]]
 
     __parameters_type__ = Parameters
 
     def __init__(
         self,
         rotation_shift: int = 15,
-        normalise: bool = False,
+        normalise: bool = True,
         nm_dist: confloat(ge=0, le=1, strict=True) = 0.45,
-        nm_type: Literal["linear", "sqrt"] = "sqrt",
+        separate_half_matching: bool = True,
         weights: Optional[List[np.ndarray]] = None,
     ) -> None:
         """Assign parameters.
 
         Args:
             rotation_shift (int): rotations allowed in matching, experessed in iris code columns. Defaults to 15.
-            nm_dist (Optional[confloat(ge=0, le = 1, strict=True)]): nonmatch distance used for normalized HD. Optional paremeter for normalized HD. Defaults to None.
+            normalise (bool = False): Flag to normalize HD. Defaults to True.
+            nm_dist (Optional[confloat(ge=0, le = 1, strict=True)]): nonmatch distance used for normalized HD. Optional paremeter for normalized HD. Defaults to 0.45.
+            separate_half_matching (bool): separate the upper and lower halves for matching. Defaults to True.
             weights (Optional[List[np.ndarray]]): list of weights table. Optional paremeter for weighted HD. Defaults to None.
         """
         super().__init__(
-            rotation_shift=rotation_shift, normalise=normalise, nm_dist=nm_dist, nm_type=nm_type, weights=weights
+            rotation_shift=rotation_shift,
+            normalise=normalise,
+            nm_dist=nm_dist,
+            separate_half_matching=separate_half_matching,
+            weights=weights,
         )
 
     def run(self, template_probe: IrisTemplate, template_gallery: IrisTemplate) -> float:
@@ -66,7 +72,7 @@ def run(self, template_probe: IrisTemplate, template_gallery: IrisTemplate) -> f
             self.params.rotation_shift,
             self.params.normalise,
             self.params.nm_dist,
-            self.params.nm_type,
+            self.params.separate_half_matching,
             self.params.weights,
         )
 

src/iris/nodes/matcher/simple_hamming_distance_matcher.py

@@ -1,8 +1,8 @@
-from pydantic import confloat, conint
+from pydantic import confloat
 
 from iris.io.dataclasses import IrisTemplate
-from iris.nodes.matcher.utils import simple_hamming_distance
 from iris.nodes.matcher.hamming_distance_matcher_interface import Matcher
+from iris.nodes.matcher.utils import simple_hamming_distance
 
 
 class SimpleHammingDistanceMatcher(Matcher):
@@ -11,7 +11,7 @@ class SimpleHammingDistanceMatcher(Matcher):
     Algorithm steps:
        1) Calculate counts of nonmatch irisbits (IB_Counts) in common unmasked region and the counts of common maskbits (MB_Counts) in common unmasked region.
        2) Calculate Hamming distance (HD) based on IB_Counts and MB_Counts.
-       3) If parameter `normalise` is True, normalize Hamming distance based on parameter `norm_mean` and parameter `norm_nb_bits`.
+       3) If parameter `normalise` is True, normalize Hamming distance based on parameter `norm_mean`.
        4) If parameter rotation_shift is > 0, repeat the above steps for additional rotations of the iriscode.
        5) Return the minimium distance from above calculations.
     """
@@ -21,7 +21,6 @@ class Parameters(Matcher.Parameters):
 
         normalise: bool
         norm_mean: confloat(ge=0, le=1)
-        norm_nb_bits: conint(gt=0)
 
     __parameters_type__ = Parameters
 
@@ -30,20 +29,15 @@ def __init__(
         rotation_shift: int = 15,
         normalise: bool = False,
         norm_mean: float = 0.45,
-        norm_nb_bits: float = 12288,
     ) -> None:
         """Assign parameters.
 
         Args:
             rotation_shift (int = 15): rotation allowed in matching, converted to columns. Defaults to 15.
             normalise (bool = False): Flag to normalize HD. Defaults to False.
             norm_mean (float = 0.45): Peak of the non-match distribution. Defaults to 0.45.
-            norm_nb_bits (float = 12288): Average number of bits visible in 2 randomly sampled iris codes. Defaults to 12288 (3/4 * total_bits_number for the iris code format v0.1).
-
         """
-        super().__init__(
-            rotation_shift=rotation_shift, normalise=normalise, norm_mean=norm_mean, norm_nb_bits=norm_nb_bits
-        )
+        super().__init__(rotation_shift=rotation_shift, normalise=normalise, norm_mean=norm_mean)
 
     def run(self, template_probe: IrisTemplate, template_gallery: IrisTemplate) -> float:
         """Match iris templates using Hamming distance.
@@ -61,6 +55,5 @@ def run(self, template_probe: IrisTemplate, template_gallery: IrisTemplate) -> f
             rotation_shift=self.params.rotation_shift,
             normalise=self.params.normalise,
             norm_mean=self.params.norm_mean,
-            norm_nb_bits=self.params.norm_nb_bits,
         )
         return score