{"id":18626292,"url":"https://github.com/anicusan/konigcell","last_synced_at":"2025-04-11T05:30:55.311Z","repository":{"id":62574542,"uuid":"368221471","full_name":"anicusan/KonigCell","owner":"anicusan","description":"Quantitative, Fast Grid-Based Fields Calculations in 2D and 3D - Residence Time Distributions, Velocity Grids, Eulerian Cell Projections etc.","archived":false,"fork":false,"pushed_at":"2023-03-31T17:13:55.000Z","size":3268,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-25T09:47:48.918Z","etag":null,"topics":["c","grid","pixels","projection","python","residence-time-distribution","visualization","voxels"],"latest_commit_sha":null,"homepage":"https://konigcell.readthedocs.io","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/anicusan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-17T14:46:31.000Z","updated_at":"2024-08-18T08:24:39.000Z","dependencies_parsed_at":"2024-11-07T04:39:59.422Z","dependency_job_id":"69108a4c-b164-4fad-ae06-417069abac54","html_url":"https://github.com/anicusan/KonigCell","commit_stats":{"total_commits":51,"total_committers":2,"mean_commits":25.5,"dds":"0.019607843137254943","last_synced_commit":"72a4b9ad1957be3fb686de2332ce6645b8fd10ed"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anicusan%2FKonigCell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anicusan%2FKonigCell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anicusan%2FKonigCell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anicusan%2FKonigCell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anicusan","download_url":"https://codeload.github.com/anicusan/KonigCell/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248347363,"owners_count":21088628,"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":["c","grid","pixels","projection","python","residence-time-distribution","visualization","voxels"],"created_at":"2024-11-07T04:37:36.295Z","updated_at":"2025-04-11T05:30:54.920Z","avatar_url":"https://github.com/anicusan.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\n[![KonigCell](https://github.com/anicusan/KonigCell/blob/main/docs/source/_static/logo.png?raw=true)](https://konigcell.readthedocs.io/en/latest/)\n\n[![PyPI version shields.io](https://img.shields.io/pypi/v/konigcell.svg?style=flat-square)](https://pypi.python.org/pypi/konigcell/)\n[![Documentation Status](https://readthedocs.org/projects/konigcell/badge/?version=latest\u0026style=flat-square)](https://konigcell.readthedocs.io/en/latest/?badge=latest)\n[![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/anicusan/KonigCell.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/anicusan/KonigCell/context:python)\n[![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/anicusan/KonigCell.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/anicusan/KonigCell/context:cpp)\n[![License: MIT](https://img.shields.io/github/license/anicusan/konigcell?style=flat-square)](https://github.com/anicusan/konigcell)\n[![PyPI pyversions](https://img.shields.io/pypi/pyversions/konigcell.svg?style=flat-square)](https://pypi.python.org/pypi/konigcell/)\n\n[![Wheels Windows](https://img.shields.io/badge/Wheels-Windows%20x86%20%7C%20x86__64-brightgreen)](https://pypi.org/project/konigcell/#files)\n[![Wheels MacOS](https://img.shields.io/badge/Wheels-MacOS%20x86__64-brightgreen)](https://pypi.org/project/konigcell/#files)\n[![Wheels Linux](https://img.shields.io/badge/Wheels-Linux%20x86__64%20%7C%20i686-brightgreen)](https://pypi.org/project/konigcell/#files)\n[![Wheel Python](https://img.shields.io/badge/Wheels-Python%203.6%20%7C%203.7%20%7C%203.8%20%7C%203.9%20%7C%203.10-brightgreen)](https://pypi.org/project/konigcell/#files)\n\n#### **Quantitative, Fast Grid-Based Fields Calculations in 2D and 3D** - Residence Time Distributions, Velocity Grids, Eulerian Cell Projections etc.\n\nThat sounds dry as heck.\n\n#### **Project moving particles' trajectories (experimental or simulated) onto 2D or 3D grids with infinite resolution.**\n\nBetter? No? Here are some figures produced by KonigCell:\n\n\n![Example Plots](https://github.com/anicusan/KonigCell/blob/main/docs/source/_static/examples.png?raw=true)\n\n*Left panel: 2D residence time distribution in a GranuTools GranuDrum imaged using Positron Emission Particle Tracking (PEPT). Two middle panels: 3D velocity distribution in the same system; voxels are rendered as a scatter plot (left) and tomogram-like 3-slice (right). Right panel: velocity vectorfield in a constricted pipe simulating a aneurysm, imaged using PEPT.*\n\n\nThis is, to my knowledge, the only library that accurately projects particle\ntrajectories onto grids - that is, taking their full projected area / volume into\naccount (and not approximating them as points / lines). It's also the only one creating\nquantitative 3D projections.\n\nAnd it is *fast* - 1,000,000 particle positions can be rasterized onto a 512x512\ngrid in 7 seconds on my 16-thread i9 CPU. The code is fully parallelised on\nthreads, processes or distributed MPI nodes.\n\n\n\n## But Why?\n\nRasterizing moving tracers onto uniform grids is a powerful way of computing statistics about a\nsystem - occupancies, velocity vector fields, modelling particle clump imaging etc. - be it \nexperimental or simulated. However, the classical approach of approximating particle trajectories\nas lines discards a lot of (most) information.\n\nHere is an example of a particle moving randomly inside a box - on a high resolution (512x512)\npixel grid, the classical approach (top row) does not yield much better statistics with increasing\nnumbers of particle positions imaged. Projecting complete trajectory **areas** onto the grid\n(KonigCell, bottom row) preserves more information about the system explored:\n\n![Increasing Positions](https://github.com/anicusan/KonigCell/blob/main/docs/source/_static/increasing_positions.png?raw=true)\n\n\nA typical strategy for dealing with information loss is to coarsen the pixel grid, resulting in\na trade-off between accuracy and statistical soundness. However, even very low resolutions\nstill yield less information using line approximations (top row). With area projections,\n**you can increase the resolution arbitrarily** and improve precision (KonigCell, bottom row):\n\n![Increasing Resolution](https://github.com/anicusan/KonigCell/blob/main/docs/source/_static/increasing_resolution.png?raw=true)\n\n\n\n\n## The KonigCell Libraries\n\nThis repository effectively hosts three libraries:\n\n- `konigcell2d`: a portable C library for 2D grid projections.\n- `konigcell3d`: a portable C library for 3D grid projections.\n- `konigcell`: a user-friendly Python interface to the two libraries above.\n\n\n\n### Installing the Python Package\n\nThis package supports Python 3.6 and above (though it might work with even older\nversions).\n\nInstall this package from PyPI:\n\n```pip install konigcell``` \n\n\nOr conda-forge:\n\n```conda install konigcell```\n\n\nIf you have a relatively standard system, the above should just download pre-compiled wheels -\nso no prior configuration should be needed.\n\n\nTo *build* this package on your specific machine, you will need a C compiler -\nthe low-level C code does not use any tomfoolery, so any compiler since the\n2000s should do.\n\n\nTo build the latest development version from GitHub:\n\n```pip install git+https://github.com/anicusan/KonigCell```\n\n\n\n### Integrating the C Libraries with your Code\n\nThe C libraries in the `konigcell2d` and `konigcell3d` directories in this repository; they\ncontain instructions for compiling and using the low-level subroutines. All code is fully\ncommented and follows a portable subset of the C99 standard - so no VLAs, weird macros or\ncompiler-specific extensions. Even MSVC compiles it!\n\nYou can run `make` in the `konigcell2d` or `konigcell3d` directories to build shared\nlibraries and the example executables under `-Wall -Werror -Wextra` like a stickler. Running\n`make` in the repository root builds both libraries.\n\nBoth libraries are effectively single-source - they should be as straightforward as possible\nto integrate in other C / C++ codebases, or interface with from higher-level programming\nlanguages.\n\n\n\n## Examples and Documentation\n\nThe `examples` directory contains some Python scripts using the high-level Python routines\nand the low-level Cython interfaces. The `konigcell2d` and `konigcell3d` directories contain\nC examples.\n\nFull documentation is available [here](https://konigcell.readthedocs.io/).\n\n```python\nimport numpy as np\nimport konigcell as kc\n\n# Generate a short trajectory of XY positions to pixellise\npositions = np.array([\n    [0.3, 0.2],\n    [0.2, 0.8],\n    [0.3, 0.55],\n    [0.6, 0.8],\n    [0.3, 0.45],\n    [0.6, 0.2],\n])\n\n# The particle radius may change\nradii = np.array([0.05, 0.03, 0.01, 0.02, 0.02, 0.03])\n\n# Values to rasterize - velocity, duration, etc.\nvalues = np.array([1, 2, 1, 1, 2, 1])\n\n# Pixellise the particle trajectories\npixels1 = kc.dynamic2d(\n    positions,\n    mode = kc.ONE,\n    radii = radii,\n    values = values[:-1],\n    resolution = (512, 512),\n)\n\npixels2 = kc.static2d(\n    positions,\n    mode = kc.ONE,\n    radii = radii,\n    values = values,\n    resolution = (512, 512),\n)\n\n# Create Plotly 1x2 subplot grid and add Plotly heatmaps of pixels\nfig = kc.create_fig(\n    nrows = 1, ncols = 2,\n    subplot_titles = [\"Dynamic 2D\", \"Static 2D\"],\n)\n\nfig.add_trace(pixels1.heatmap_trace(), row = 1, col = 1)\nfig.add_trace(pixels2.heatmap_trace(), row = 1, col = 2)\n\nfig.show()\n```\n\n![Static-Dynamic 2D](https://github.com/anicusan/KonigCell/blob/main/docs/source/_static/static_dynamic2d.png?raw=true)\n\n\n\n## Contributing\nYou are more than welcome to contribute to this library in the form of library\nimprovements, documentation or helpful examples; please submit them either as:\n\n- GitHub issues.\n- Pull requests (superheroes only).\n- Email me at \u003ca.l.nicusan@bham.ac.uk\u003e.\n\n\n\n## Acknowledgements\nI would like to thank the Formulation Engineering CDT @School of Chemical\nEngineering and the Positron Imaging Centre @School of Physics and\nAstronomy, University of Birmingham for supporting my work.\n\nAnd thanks to Dr. Kit Windows-Yule for putting up with my bonkers ideas.\n\n\n\n## Citing\nIf you use this library in your research, you are kindly asked to cite:\n\n\u003e [Paper after publication]\n\n\nThis library would not have been possible without the excellent `r3d` library\n(https://github.com/devonmpowell/r3d) which forms the very core of the C\nsubroutines; if you use KonigCell in your work, please also cite:\n\n\u003e Powell D, Abel T. An exact general remeshing scheme applied to physically conservative voxelization. Journal of Computational Physics. 2015 Sep 15;297:340-56.\n\n\n\n## Licensing\nKonigCell is MIT licensed. Enjoy.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanicusan%2Fkonigcell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanicusan%2Fkonigcell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanicusan%2Fkonigcell/lists"}