Metadata-Version: 2.4
Name: hbs
Version: 1.0.3
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
Requires-Dist: numpy
Requires-Dist: scipy
Provides-Extra: plot
Requires-Dist: matplotlib; extra == "plot"
Provides-Extra: boundary
Requires-Dist: opencv-python; extra == "boundary"
Provides-Extra: all
Requires-Dist: matplotlib; extra == "all"
Requires-Dist: opencv-python; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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
- `conformal_welding.py`: Conformal welding algorithm implementation
- `mesh.py`: Mesh generation and processing
- `plotting.py`: Optional plotting helpers (matplotlib is NOT required for compute)
- `utils/`:
  - `boundary.py`: Boundary processing tools (requires opencv-python)
  - `cast.py`: Complex ↔ real array conversion
  - `geodesic_welding.py`: Geodesic welding
  - `mobius.py`: Möbius transformations
  - `poisson.py`: Poisson integral implementation
  - `zipper.py`: Zipper algorithm implementation
- `qc/`: Quasiconformal mapping algorithms
  - `beltrami.py`: Beltrami coefficient computation + mu_chop
  - `lsqc.py`: Least squares quasiconformal mapping algorithm

Top-level `import hbs` exposes the full public API:
`get_hbs`, `reconstruct_from_hbs`, `get_beltrami_coefficient`, `lsqc_solver`,
`mu_chop`, `get_conformal_welding`, `get_unit_disk`, `get_rect`,
`get_unit_disk_in_rect`, `Mesh`, `DiskMesh`.

Backward-compatible shims keep old internal paths working:
`hbs.qc.bc` → `hbs.qc.beltrami`, `hbs.utils.tool_functions` → `hbs.utils.cast` + `hbs.qc.beltrami`.

## Usage Example

Compute HBS from image



```python
from hbs.utils.boundary import get_boundary
from hbs import get_hbs

# Boundary points extraction
# 
# we don't actually restrict the method of boundary extraction,
# but this package provides a simple implementation as follows
img_path = 'img/example.jpg'
circle_point_num = 1000
bound = get_boundary(img_path, bound_point_num)

# HBS computing
# 
# it requires boundary points arranged in clockwise order as input, in `np.complex`
density = 0.01
bound_point_num = 250
hbs, hbs_mapping, 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)
```

Compute conformal welding from image

```python
from hbs.utils.boundary import get_boundary
from hbs.conformal_welding import get_conformal_welding

# Boundary points extraction
img_path = 'img/example.jpg'
bound_point_num = 250
bound = get_boundary(img_path, bound_point_num)

# Conformal welding computing
# 
# it also requires boundary points arranged in clockwise order as input, in `np.complex`
cw = get_conformal_welding(bound)
```

Please also refer to `example.ipynb`

## Dependencies

- NumPy
- SciPy

Optional (extras):

- `hbs[plot]` → Matplotlib (for `hbs.plotting`)
- `hbs[boundary]` → OpenCV (for `hbs.utils.boundary`)
- `hbs[all]` → both

Core compute (HBS, mesh, LSQC, welding) works without matplotlib.

## Contributing

Contributions are welcome via pull requests.

## Code Author
-  Chenran Lin
