type hints and python >= 3.6

examples.py

@@ -1,8 +1,23 @@
 from hilbertcurve.hilbertcurve import HilbertCurve
 
-# we can go from distance along a curve to coordinates
-# in 2 dimensions with p=1 there are only 4 locations on the curve
-# [0, 0], [0, 1], [1, 1], [1, 0]
+# When using a single iteration (p=1) in 2 dimensions (N=2) there are only 4
+# locations on the curve
+# distance | coordinates
+# 0        | [0, 0]
+# 1        | [0, 1]
+# 2        | [1, 1]
+# 3        | [1, 0]
+
+
+# calculate distances along a hilbert curve given coordinates
+p = 1
+N = 2
+hilbert_curve = HilbertCurve(p, N)
+for coords in [[0,0], [0,1], [1,1], [1,0]]:
+    dist = hilbert_curve.distance_from_coordinates(coords)
+    print(f'distance(x={coords}) = {dist}')
+
+# calculate coordinates given distances along a hilbert curve
 p = 1
 N = 2
 hilbert_curve = HilbertCurve(p, N)
@@ -20,3 +35,8 @@
 ii = 123456789101112131415161718192021222324252627282930
 coords = hilbert_curve.coordinates_from_distance(ii)
 print('coords(h={},p={},N={}) = {}'.format(ii, p, N, coords))
+
+
+coords = [121075, 67332, 67326, 108879, 26637, 43346, 23848, 1551, 68130, 84004]
+dist = hilbert_curve.distance_from_coordinates(coords)
+print(f'distance(x={coords}) = {dist}')

hilbertcurve/__init__.py

@@ -1,4 +1,4 @@
 """Metadata for this package."""
 
 __package_name__ = "hilbertcurve"
-__version__ = "1.0.3"
+__version__ = "1.0.4"

hilbertcurve/hilbertcurve.py

@@ -11,21 +11,22 @@
 discrete distances along the Hilbert curve (indexed from :math:`0` to
 :math:`2^{N p} - 1`).
 """
+from typing import Iterable, List
 
 
-def _binary_repr(num, width):
+def _binary_repr(num: int, width:int) -> str:
     """Return a binary string representation of `num` zero padded to `width`
     bits."""
     return format(num, 'b').zfill(width)
 
 
 class HilbertCurve:
 
-    def __init__(self, p, n):
+    def __init__(self, p: int, n: int) -> None:
         """Initialize a hilbert curve with,
 
         Args:
-            p (int): iterations to use in the hilbert curve
+            p (int): iterations to use in constructing the hilbert curve
             n (int): number of dimensions
         """
         if p <= 0:
@@ -41,7 +42,7 @@ def __init__(self, p, n):
         # maximum coordinate value in any dimension
         self.max_x = 2**self.p - 1
 
-    def _hilbert_integer_to_transpose(self, h):
+    def _hilbert_integer_to_transpose(self, h: int) -> List[int]:
         """Store a hilbert integer (`h`) as its transpose (`x`).
 
         Args:
@@ -55,7 +56,7 @@ def _hilbert_integer_to_transpose(self, h):
         x = [int(h_bit_str[i::self.n], 2) for i in range(self.n)]
         return x
 
-    def _transpose_to_hilbert_integer(self, x):
+    def _transpose_to_hilbert_integer(self, x: List[int]) -> int:
         """Restore a hilbert integer (`h`) from its transpose (`x`).
 
         Args:
@@ -69,7 +70,7 @@ def _transpose_to_hilbert_integer(self, x):
         h = int(''.join([y[i] for i in range(self.p) for y in x_bit_str]), 2)
         return h
 
-    def coordinates_from_distance(self, h):
+    def coordinates_from_distance(self, h: int) -> List[int]:
         """Return the coordinates for a given hilbert distance.
 
         Args:
@@ -111,7 +112,7 @@ def coordinates_from_distance(self, h):
         # done
         return x
 
-    def distance_from_coordinates(self, x_in):
+    def distance_from_coordinates(self, x_in: List[int]) -> int:
         """Return the hilbert distance for a given set of coordinates.
 
         Args:

setup.py

@@ -62,5 +62,5 @@ def find_long_description() -> str:
         "Programming Language :: Python :: 3 :: Only",
     ],
     keywords="fractal space-filling-curves hilbert hilbert-curve python python3 wikidata parser",
-    python_requires=">=3.5",
+    python_requires=">=3.6",
 )