hbs 0.1.1__tar.gz

hbs-0.1.1/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.1
+Name: hbs
+Version: 0.1.1
+Summary: Python library for computing Harmonic Beltrami Signature(HBS)
+Home-page: https://github.com/ChanceAroundYou/hbs_python
+Author: Lin Chenran
+Author-email: chenranlin.17@gmail.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# HBS - Harmonic Beltrami Signature
+
+This is a Python library for computing Harmonic Beltrami Signature(HBS). It provides a set of tools for boundary conditions, mesh generation, conformal welding and other mathematical problems, particularly suited for numerical computations in complex analysis.
+
+## Reference
+This implementation is based on the paper:
+
+**Harmonic Beltrami Signature: A Novel 2D Shape Representation for Object Classification**  
+Chenran Lin, Lok Ming Lui
+DOI: [10.1137/22M1470852](https://doi.org/10.1137/22M1470852)
+
+## Installation
+
+Install directly from PyPI:
+```bash
+pip install hbs
+```
+
+Or install from source:
+1. Clone this repository:
+   ```bash
+   git clone https://github.com/ChanceAroundYou/hbs_python.git
+   ```
+2. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+## Main Modules
+
+- `hbs.py`: HBS algorithm for computing HBS and recontructing shape from HBS
+- `boundary.py`: Boundary processing tools
+- `conformal_welding.py`: Conformal welding algorithm implementation
+- `mesh.py`: Mesh generation and processing
+- `utils/`:
+  - `geodesic_welding.py`: Geodesic welding
+  - `mobius.py`: Möbius transformations
+  - `poisson.py`: Poisson integral implementation
+  - `tool_functions.py`: Utility functions
+  - `zipper.py`: Zipper algorithm implementation
+- `qc/`: Quasiconformal mapping algorithms
+  - `bc.py`: Beltrami coefficient computation
+  - `lsqc.py`: Least squares quasiconformal mapping algorithm
+
+## Usage Example
+
+Compute HBS from image
+
+```python
+from boundary import get_boundary
+from hbs import get_hbs
+
+img_path = 'img/example.jpg'
+bound = get_boundary(img_path, bound_point_num)
+hbs, he, cw, disk = get_hbs(bound, circle_point_num, density)
+```
+
+Reconstruct shape from HBS
+```python
+from hbs import reconstruct_from_hbs
+
+## `disk` must be a DiskMesh corresponding to give `hbs`
+bound, _, _, _ = reconstruct_from_hbs(hbs, disk)
+```
+
+Please also refer to `example.ipynb`
+
+## Dependencies
+
+- NumPy
+- SciPy
+- Matplotlib
+- Opencv
+
+## Contributing
+
+Contributions are welcome via pull requests.
+
+## Code Author
+-  Chenran Lin

hbs-0.1.1/README.md

@@ -0,0 +1,80 @@
+# HBS - Harmonic Beltrami Signature
+
+This is a Python library for computing Harmonic Beltrami Signature(HBS). It provides a set of tools for boundary conditions, mesh generation, conformal welding and other mathematical problems, particularly suited for numerical computations in complex analysis.
+
+## Reference
+This implementation is based on the paper:
+
+**Harmonic Beltrami Signature: A Novel 2D Shape Representation for Object Classification**  
+Chenran Lin, Lok Ming Lui
+DOI: [10.1137/22M1470852](https://doi.org/10.1137/22M1470852)
+
+## Installation
+
+Install directly from PyPI:
+```bash
+pip install hbs
+```
+
+Or install from source:
+1. Clone this repository:
+   ```bash
+   git clone https://github.com/ChanceAroundYou/hbs_python.git
+   ```
+2. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+## Main Modules
+
+- `hbs.py`: HBS algorithm for computing HBS and recontructing shape from HBS
+- `boundary.py`: Boundary processing tools
+- `conformal_welding.py`: Conformal welding algorithm implementation
+- `mesh.py`: Mesh generation and processing
+- `utils/`:
+  - `geodesic_welding.py`: Geodesic welding
+  - `mobius.py`: Möbius transformations
+  - `poisson.py`: Poisson integral implementation
+  - `tool_functions.py`: Utility functions
+  - `zipper.py`: Zipper algorithm implementation
+- `qc/`: Quasiconformal mapping algorithms
+  - `bc.py`: Beltrami coefficient computation
+  - `lsqc.py`: Least squares quasiconformal mapping algorithm
+
+## Usage Example
+
+Compute HBS from image
+
+```python
+from boundary import get_boundary
+from hbs import get_hbs
+
+img_path = 'img/example.jpg'
+bound = get_boundary(img_path, bound_point_num)
+hbs, he, cw, disk = get_hbs(bound, circle_point_num, density)
+```
+
+Reconstruct shape from HBS
+```python
+from hbs import reconstruct_from_hbs
+
+## `disk` must be a DiskMesh corresponding to give `hbs`
+bound, _, _, _ = reconstruct_from_hbs(hbs, disk)
+```
+
+Please also refer to `example.ipynb`
+
+## Dependencies
+
+- NumPy
+- SciPy
+- Matplotlib
+- Opencv
+
+## Contributing
+
+Contributions are welcome via pull requests.
+
+## Code Author
+-  Chenran Lin

hbs-0.1.1/hbs/__init__.py

@@ -0,0 +1,6 @@
+"""HBS - Harmonic Beltrami Signature package.
+
+A Python library for complex analysis and conformal mapping computations.
+"""
+
+from .hbs import get_hbs, reconstruct_from_hbs

hbs-0.1.1/hbs/boundary.py

@@ -0,0 +1,155 @@
+import cv2
+import matplotlib.pyplot as plt
+import numpy as np
+from scipy.interpolate import CubicSpline, PchipInterpolator
+
+
+def get_boundary(image_path, num_points=250):
+    """
+    Process the image to extract boundary, apply anti-aliasing, and resample.
+
+    Parameters:
+    image_path: Input image path
+    num_points: Number of resampled points
+
+    Returns:
+    resampled_points: List of resampled boundary points
+    """
+    # Extract boundary points
+    boundary_points = extract_boundary_points(image_path)
+    # Apply anti-aliasing
+    smoothed_points = anti_aliasing(boundary_points)
+    # Resample to the specified number of points
+    resampled_points = smooth_resample(smoothed_points, num_points)
+    return resampled_points
+
+
+def extract_boundary_points(image_path):
+    """
+    Extract ordered boundary points from a near black-and-white image.
+
+    Parameters:
+    image_path: Input image path
+
+    Returns:
+    boundary_points: List of ordered boundary points, format [(x1, y1), (x2, y2), ...]
+    """
+    # Read the image and convert to grayscale
+    img = cv2.imread(image_path, cv2.IMREAD_GRAYSCALE)
+
+    # Determine if the image is black-on-white or white-on-black
+    if np.mean(img) > 127:
+        # White-on-black image, invert it
+        img = cv2.bitwise_not(img)
+
+    # Binarize the image
+    _, binary = cv2.threshold(img, 127, 255, cv2.THRESH_BINARY)
+
+    # Find contours (using CHAIN_APPROX_NONE to get all boundary points)
+    contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_NONE)
+
+    # Get the largest contour (assuming there's only one main shape in the image)
+    main_contour = max(contours, key=cv2.contourArea)
+
+    # Return the contour points directly, without sorting or anti-aliasing
+    return main_contour.reshape(-1, 2)
+
+
+def anti_aliasing(points, kernel_size=5):
+    """
+    Apply anti-aliasing to boundary points.
+
+    Parameters:
+    points: List of original boundary points
+
+    Returns:
+    smoothed_points: List of smoothed boundary points
+    """
+    # Use Gaussian blur for smoothing
+    x = cv2.GaussianBlur(points[:, 0].astype("float32"), (kernel_size, kernel_size), 0)
+    y = cv2.GaussianBlur(points[:, 1].astype("float32"), (kernel_size, kernel_size), 0)
+    return np.column_stack((x, y))
+
+
+def plot_boundary(boundary, with_line=True, scale=1):
+    num_points = boundary.shape[0]
+    x_min, x_max = np.min(boundary[:, 0]), np.max(boundary[:, 0])
+    y_min, y_max = np.min(boundary[:, 1]), np.max(boundary[:, 1])
+    aspect_ratio = (x_max - x_min) / (y_max - y_min)
+
+    fig_size = (num_points / 60 * scale * aspect_ratio, num_points / 60 * scale)
+    plt.figure(figsize=fig_size)
+    if with_line:
+        plt.plot(
+            boundary[:, 0],
+            boundary[:, 1],
+            linestyle="-",
+            linewidth=1 * scale,
+            color="white",
+            label="Boundary Line",
+        )
+    plt.scatter(
+        boundary[:, 0],
+        boundary[:, 1],
+        marker="o",
+        s=15 * scale,
+        edgecolor="lightgreen",
+        facecolor="none",
+        label="Boundary Points",
+    )
+    plt.show()
+
+
+def smooth_resample(points, num_points=None):
+    """
+    Smoothly and uniformly resample the boundary points matrix, generating a matrix of m points.
+    :param points: nx2 matrix, original boundary point coordinates
+    :param num_points: Number of resampled points
+    :return: mx2 matrix, resampled boundary points
+    """
+    if num_points is None:
+        num_points = points.shape[0]
+
+    # Check if the boundary is closed
+    is_closed = np.all(np.abs(points[0, :] - points[-1, :]) < 1e-8)
+    if not is_closed:
+        points = np.vstack([points, points[0, :]])  # Close the boundary if not closed
+
+    # Calculate cumulative arc length
+    diffs = np.diff(points, axis=0)
+    dists = np.sqrt(np.sum(diffs**2, axis=1))
+    cum_dists = np.concatenate([[0], np.cumsum(dists)])
+    total_length = cum_dists[-1]
+
+    # Spline interpolation settings
+    t = cum_dists
+    x = points[:, 0]
+    y = points[:, 1]
+
+    if is_closed:
+        # Periodic cubic spline interpolation (closed curve)
+        ppx = CubicSpline(t, x, bc_type="periodic")
+        ppy = CubicSpline(t, y, bc_type="periodic")
+    else:
+        # Shape-preserving piecewise cubic interpolation (open curve)
+        ppx = PchipInterpolator(t, x)
+        ppy = PchipInterpolator(t, y)
+
+    # Generate uniform parameters
+    if is_closed:
+        t_new = np.linspace(0, total_length, num_points + 2)
+        t_new = t_new[:-1]  # Avoid duplicate start and end points
+    else:
+        t_new = np.linspace(0, total_length, num_points + 1)
+
+    # Calculate new points
+    x_new = ppx(t_new)
+    y_new = ppy(t_new)
+    resampled_points = np.column_stack([x_new, y_new])
+    return resampled_points[:-1, :]
+
+
+if __name__ == "__main__":
+    # 示例用法
+    boundary_points = extract_boundary_points("test_image.png")
+    print(f"提取的边界点数量：{len(boundary_points)}")

hbs-0.1.1/hbs/conformal_welding.py

@@ -0,0 +1,150 @@
+import matplotlib.pyplot as plt
+import numpy as np
+from scipy.interpolate import interp1d
+
+from utils.mobius import mobius, mobius_inv
+from utils.tool_functions import to_complex
+from utils.zipper import zipper, zipper_params
+
+
+class ConformalWelding:
+    def __init__(
+        self,
+        x: np.ndarray[np.complexfloating],
+        y: np.ndarray[np.complexfloating],
+        params: np.ndarray[np.complexfloating],
+    ):
+        """
+        Initialize the ConformalWelding class.
+
+        Parameters:
+        x (np.ndarray): Complex ndarray of shape (n,) representing initial x points.
+        y (np.ndarray): Complex ndarray of shape (n,) representing initial y points.
+        params (np.ndarray): Complex ndarray of shape (n+1,) representing parameters.
+        """
+        assert (
+            x.ndim == y.ndim == params.ndim == 1
+            and np.issubdtype(x.dtype, np.complexfloating)
+            and np.issubdtype(y.dtype, np.complexfloating)
+            and np.issubdtype(params.dtype, np.complexfloating)
+        ), "Input must be 1D complex array"
+        assert len(x) == len(y) == len(params) - 1, (
+            "Length of x, y, params must be n, n, n+1"
+        )
+
+        self.params = params
+        self._set_init_x(x)
+        self._set_init_y(y)
+
+    def _set_init_x(self, x: np.ndarray[np.complexfloating]):
+        self.init_x = x
+        self.init_x_angle = np.angle(x)
+        self.x = x
+
+    def _set_init_y(self, y: np.ndarray[np.complexfloating]):
+        self.init_y = y
+        self.y = y
+
+    def uniquify(self):
+        x_angle, idx = np.unique(np.angle(self.init_x), return_index=True)
+        x = np.exp(x_angle * 1j)
+        y = self.init_y[idx]
+        y = np.exp(np.angle(y) * 1j)
+
+        self._set_init_x(x)
+        self._set_init_y(y)
+
+    def linear_interp(self, num: int):
+        x_angle_regular = np.arange(0, 2 * np.pi, 2 * np.pi / num)
+        self.x = np.exp(x_angle_regular * 1j)
+
+        inter_func = interp1d(
+            np.concatenate(
+                [
+                    self.init_x_angle - 2 * np.pi,
+                    self.init_x_angle,
+                    self.init_x_angle + 2 * np.pi,
+                ]
+            ),
+            np.concatenate([self.init_y, self.init_y, self.init_y]),
+            kind="linear",
+        )
+        y = inter_func(x_angle_regular)
+        self.y = np.exp(np.angle(y / y[0]) * 1j)
+
+    def rotate_x(self, r):
+        x_angle = np.mod(self.init_x_angle - r, 2 * np.pi)
+        x = np.exp(x_angle * 1j)
+        self._set_init_x(x)
+
+    def x_post_norm(self):
+        """
+        对外部点进行后归一化
+        :param z: 输入点
+        :param params: 参数
+        :return: 归一化后的点，a 和 theta 参数
+        """
+        zinf = zipper_params([np.inf], self.params)
+        a = -1 / np.conj(zinf)
+        theta = 0
+        x = mobius_inv(self.x, a, theta)
+        x = np.flipud(x)
+        self._set_init_x(x)
+
+    def y_post_norm(self):
+        """
+        对内部点进行后归一化
+        :param z: 输入点
+        :return: 归一化后的点，a 和 theta 参数
+        """
+        p = np.append(self.y, [0, 1])
+        while True:
+            center = np.mean(p[:-2])
+            if np.abs(center) <= np.finfo(float).eps:
+                break
+            p = mobius(p, center)
+
+        y = p[:-2]
+        # y = np.flipud(y)
+        self._set_init_y(y)
+
+    def plot_x(self):
+        plt.gca().set_aspect("equal", adjustable="box")
+        plt.scatter(self.x.real, self.x.imag)
+        plt.show()
+
+    def plot_y(self):
+        plt.gca().set_aspect("equal", adjustable="box")
+        plt.scatter(self.y.real, self.y.imag)
+        plt.show()
+
+    def plot(self, is_interp=True):
+        plt.gca().set_aspect("equal", adjustable="box")
+        x_angle = np.angle(self.x)
+        y_angle = np.angle(self.y)
+        x_angle = np.mod(x_angle, 2 * np.pi)
+        y_angle = np.mod(y_angle, 2 * np.pi)
+        if is_interp:
+            plt.plot(x_angle, y_angle, linestyle="-", linewidth=2)
+        else:
+            plt.scatter(x_angle, y_angle, s=2)
+        plt.show()
+
+
+def get_conformal_welding(bound: np.ndarray[np.floating]) -> ConformalWelding:
+    assert (
+        bound.ndim == 2
+        and bound.shape[1] == 2
+        and np.issubdtype(bound.dtype, np.floating)
+    ), "bound must be n x 2 real array with float type"
+
+    bound = to_complex(bound)
+    x, _, x_params = zipper(bound)
+    # x = np.flipud(x)
+    y, _, _ = zipper(np.flipud(bound))
+
+    cw = ConformalWelding(x, y, x_params)
+    cw.x_post_norm()
+    cw.y_post_norm()
+    cw.uniquify()
+    return cw

hbs-0.1.1/hbs/hbs.py

@@ -0,0 +1,103 @@
+import numpy as np
+
+from hbs.conformal_welding import ConformalWelding, get_conformal_welding
+from utils.geodesic_welding import geodesic_welding
+from hbs.mesh import DiskMesh, get_unit_disk
+from qc import get_beltrami_coefficient, lsqc_solver
+from utils.poisson import integral as poisson_integral
+from utils.tool_functions import to_complex, to_real
+
+
+def get_hbs(
+    bound: np.ndarray[np.floating],
+    circle_point_num: int = 500,
+    density: float = 0.01,
+    disk: DiskMesh = None,
+) -> tuple[
+    np.ndarray[np.complexfloating],
+    np.ndarray[np.floating],
+    ConformalWelding,
+    DiskMesh,
+]:
+    """
+    Get Beltrami coefficients from boundary points
+    :param `bound`: `n x 2` array, boundary points
+    :param `circle_point_num`: number of points on the circle
+    :param `density`: density of the mesh
+    :param `disk`: DiskMesh object
+    :return:
+        `hbs`: `n` x 1 complex array, Beltrami coefficients defined on triangles
+        `he`: `n` x 1 float array, harmonice extension of `hbs`
+        `cw`: ConformalWelding object
+        `disk`: DiskMesh object
+    """
+    if disk is None:
+        disk = get_unit_disk(density, circle_point_num)
+
+    cw = get_conformal_welding(bound)
+
+    r = 0
+    while True:
+        cw.rotate_x(r / 2)
+        cw.linear_interp(circle_point_num)
+        he = poisson_integral(disk.in_vert, cw.x, cw.y)
+        hbs = get_beltrami_coefficient(he, disk)
+
+        excluded_idx = np.isnan(hbs) + np.linalg.norm(disk.face_center, axis=1) == 0
+        r = np.angle(np.sum(hbs[~excluded_idx]))
+
+        if abs(r) <= 5e-3:
+            he_angle = np.angle(np.sum(hbs * to_complex(disk.face_center)))
+            if he_angle < 0 or he_angle == np.pi:
+                r += 2 * np.pi
+            else:
+                break
+
+    return hbs, he, cw, disk
+
+
+def reconstruct_from_hbs(
+    hbs: np.ndarray[np.complexfloating], disk: DiskMesh
+):
+    """
+    Reconstruct original shape from HBS
+    :param `hbs`: complex array with length `disk.face_num`, Beltrami coefficients defined on triangles
+    :param `disk`: DiskMesh object
+    :return:
+        `bound_points`: `disk.circle_num` x 2 array, boundary points
+        `in_points`: `disk.in_vert_num` x 2 array, inner points
+        `out_points`: `disk.out_vert_num` x 2 array, outer points
+        `mapping`: `disk.vert_num` x 2 array, vertex coordinates of the solved mapping
+    """
+    assert isinstance(disk, DiskMesh), "`disk` must be DiskMesh object"
+
+    assert isinstance(hbs, np.ndarray) and np.issubdtype(
+        hbs.dtype, np.complexfloating
+    ), "`hbs` must be complex array"
+    assert hbs.ndim == 1 and hbs.shape[0] == disk.face_num, (
+        "the length of `hbs` is `n` and `n` is the number of faces"
+    )
+
+    target = np.array([[1, 0], [0, 0]], dtype=np.float64)
+
+    one_pos = np.all(disk.vert == target[0], axis=1)
+    zero_pos = np.all(disk.vert == target[1], axis=1)
+    landmark = np.where(one_pos | zero_pos)[0]
+
+    mapping = lsqc_solver(hbs, landmark, target, disk)
+    bound_points = mapping[: disk.circle_num]
+    in_points = mapping[: disk.in_vert_num + disk.circle_num]
+    out_points = mapping[disk.in_vert_num + disk.circle_num :]
+
+    in_points, out_points = geodesic_welding(
+        to_complex(in_points),
+        to_complex(out_points),
+        to_complex(bound_points),
+        to_complex(disk.circle),
+    )
+    in_points = to_real(in_points)
+    out_points = to_real(out_points)
+
+    bound_points = in_points[: disk.circle_num]
+    in_points = in_points[disk.circle_num :]
+    return bound_points, in_points, out_points, mapping