{"id":18129114,"url":"https://github.com/yoyolicoris/kamui","last_synced_at":"2025-12-14T18:21:18.851Z","repository":{"id":195152860,"uuid":"691700838","full_name":"yoyolicoris/kamui","owner":"yoyolicoris","description":null,"archived":false,"fork":false,"pushed_at":"2024-12-27T12:14:33.000Z","size":1910,"stargazers_count":23,"open_issues_count":7,"forks_count":5,"subscribers_count":3,"default_branch":"dev","last_synced_at":"2025-04-06T00:49:11.353Z","etag":null,"topics":["graph-cuts","insar","integer-linear-programming","minimum-cost-flow","mri","phase-unwrapping"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yoyolicoris.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-14T17:50:06.000Z","updated_at":"2025-04-05T09:05:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"a1b812f4-d932-414b-b7fc-899d7239c91c","html_url":"https://github.com/yoyolicoris/kamui","commit_stats":null,"previous_names":["yoyololicon/kamui","yoyolicoris/kamui"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoyolicoris%2Fkamui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoyolicoris%2Fkamui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoyolicoris%2Fkamui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoyolicoris%2Fkamui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yoyolicoris","download_url":"https://codeload.github.com/yoyolicoris/kamui/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249067152,"owners_count":21207392,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["graph-cuts","insar","integer-linear-programming","minimum-cost-flow","mri","phase-unwrapping"],"created_at":"2024-11-01T10:04:10.117Z","updated_at":"2025-12-14T18:21:18.791Z","avatar_url":"https://github.com/yoyolicoris.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kamui\n[![Lint](https://github.com/yoyololicon/kamui/actions/workflows/black.yml/badge.svg)](https://github.com/yoyololicon/kamui/actions/workflows/black.yml)\n[![Upload Python Package](https://github.com/yoyololicon/kamui/actions/workflows/python-publish.yml/badge.svg)](https://github.com/yoyololicon/kamui/actions/workflows/python-publish.yml)\n[![PyPI version](https://badge.fury.io/py/kamui.svg)](https://badge.fury.io/py/kamui)\n\n\nKamui is a python package for robust and accurate phase unwrapping on 2-D, 3-D, or sparse data. \n\nKamui unwrap the phases by viewing the data points as vertices $V$ connected with edges $E$ and solving the following integer linear programming (ILP) problem:\n\n```math\n\\min_{k} w^T |k|,\n```\n\n```math\n\\text{s.t.} Ak = -A\\frac{x}{2\\pi},\n```\nwhere $`k_{i \\in [0, M)} \\in \\mathbb{Z}`$ is the edge ambiguities to be computed, $`w_{i \\in [0, M)} \\in \\mathbb{R}^+`$ is the weights, $`x_{i \\in [0, M)} = (V_v - V_u + \\pi) \\pmod {2\\pi} - \\pi |  (u, v) = E_i`$ is the pseudo phase derivatives, $`M = |E|`$. \n$`A_{ij} \\in \\{-1, 0, 1\\} | i \\in [0, N) \\cap j \\in [0, M)`$ and $N$ is the number of elementary cycles enclosed by $E$.\n\nThis formulation is based on the fact that the true phase differences, $2\\pi k + x$, should fulfill the irrotationality constraint, which means the summation of phase derivatives of each elementary cycles is zero.\nThis is the general form of the network programming approach proposed in the paper \"[A novel phase unwrapping method based on network programming](https://ieeexplore.ieee.org/document/673674)\".\n\nUnwrapping phase with Kamui can be computationally heavy.\nAcceleration techniques, such as dividing the graph into subgraphs, will be implemented in the future.\n\n## Installation\n\n```commandline\npip install kamui\n```\n\nKamui also provides [PUMA](https://ieeexplore.ieee.org/document/4099386), a fast and robust phase unwrapping algorithm based on graph cuts as an alternative.\nTo install PUMA, run\n\n```commandline\npip install kamui[extra]\n```\n\nHowever, it uses the original maxflow implementation by Vladimir Kolmogorov with GPL license.\nPlease follow the licensing instruction in [PyMaxflow](http://pmneila.github.io/PyMaxflow/#indices-and-tables) if you use this version of Kamui.\n\n\n## Usage\n\nFor regular 2-D or 3-D data such as interferograms, use `kamui.unwrap_dimensional`:\n\n```python\nimport numpy as np\n\ndef unwrap_dimensional(\n    x: np.ndarray,\n    start_pixel: Optional[Union[Tuple[int, int], Tuple[int, int, int]]] = None,\n    use_edgelist: bool = False,\n    **kwargs\n) -\u003e np.ndarray:\n    \"\"\"\n    Unwrap the phase of a 2-D or 3-D array.\n\n    Parameters\n    ----------\n    x : 2-D or 3-D np.ndarray\n        The phase to be unwrapped.\n    start_pixel : (2,) or (3,) tuple\n        the reference pixel to start unwrapping.\n        Default to (0, 0) for 2-D data and (0, 0, 0) for 3-D data.\n    use_edgelist : bool\n        Whether to use the edgelist method.\n        Default to False.\n    kwargs : dict\n        Other arguments passed to `kamui.unwrap_arbitrary`.\n\n    Returns\n    -------\n    np.ndarray\n        The unwrapped phase of the same shape as x.\n    \"\"\"\n```\n\nFor sparse data, use `kamui.unwrap_arbitrary`:\n\n```python\nimport numpy as np\n\ndef unwrap_arbitrary(\n    psi: np.ndarray,\n    edges: np.ndarray,\n    simplices: Iterable[Iterable[int]] = None,\n    method: str = \"ilp\",\n    period: float = 2 * np.pi,\n    start_i: int = 0,\n    **kwargs,\n) -\u003e np.ndarray:\n    \"\"\"\n    Unwrap the phase of arbitrary data.\n\n    Parameters\n    ----------\n    psi : 1D np.ndarray of shape (P,)\n        The phase (vertices) to be unwrapped.\n    edges : 2-D np.ndarray of shape (M, 2)\n        The edges of the graph.\n    simplices : Iterable[Iterable[int]] of length (N,)\n        Each element is a list of vertices that form a simplex (a.k.a elementary cycle).\n        The connections should be consistent with the edges.\n        This is also used to compute automatic weights for each edge.\n        If not provided and method is \"ilp\", an edgelist-based ILP solver will be used without weighting.\n    method : str\n        The method to be used. Valid options are \"ilp\" and \"gc\", where \"gc\" correponds to PUMA.\n        Default to \"ilp\".\n    period : float\n        The period of the phase.\n        Default to 2 * np.pi.\n    start_i : int\n        The index of the reference vertex to start unwrapping.\n        Default to 0.\n    kwargs : dict\n        Other arguments passed to the solver.\n\n    Returns\n    -------\n    np.ndarray\n        The unwrapped phase of the same shape as psi.\n    \"\"\"\n```\n\n## Examples\n\n- [Unwrapping on 2-D synthetic data](/examples/synthetic_images.ipynb)\n\n## TODO\n\n- [ ] subgraph division\n- [x] edges-based custom weighting\n- [ ] vertices-based custom weighting\n\n## References\n\n- [scikit-image/scikit-image/#4622](https://github.com/scikit-image/scikit-image/issues/4622)\n- [my medium blogpost](https://medium.com/@ILoveJK/%E7%9B%B8%E4%BD%8D%E9%87%8D%E5%BB%BA%E8%88%87%E5%9C%96%E5%AD%B8-phase-unwrapping-using-minimum-cost-network-flow-%E4%B8%89-b64732901f17)\n- [A novel phase unwrapping method based on network programming](https://ieeexplore.ieee.org/document/673674)\n- [Phase Unwrapping via Graph Cuts](https://ieeexplore.ieee.org/document/4099386)\n- [Edgelist phase unwrapping algorithm for time series InSAR analysis](https://opg.optica.org/josaa/abstract.cfm?uri=josaa-27-3-605)\n- [Time Series Phase Unwrapping Based on Graph Theory and Compressed Sensing](https://ieeexplore.ieee.org/document/9387451?arnumber=9387451)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyoyolicoris%2Fkamui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyoyolicoris%2Fkamui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyoyolicoris%2Fkamui/lists"}