{"id":16636315,"url":"https://github.com/s-ol/gpwfc","last_synced_at":"2025-03-21T15:31:41.187Z","repository":{"id":69399437,"uuid":"133382363","full_name":"s-ol/gpWFC","owner":"s-ol","description":"openCL-accelerated python implementation of the Wave Function Collapse procgen algorithm","archived":false,"fork":false,"pushed_at":"2018-10-29T06:15:47.000Z","size":41,"stargazers_count":50,"open_issues_count":0,"forks_count":1,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-01T07:35:22.359Z","etag":null,"topics":["algorithm","gamedev","machine-learning","opencl","procedural-generation","python","wfc"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/s-ol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2018-05-14T15:25:21.000Z","updated_at":"2024-04-11T17:35:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"cf3962fa-9c34-4016-b81d-7938bd1d3bea","html_url":"https://github.com/s-ol/gpWFC","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s-ol%2FgpWFC","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s-ol%2FgpWFC/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s-ol%2FgpWFC/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s-ol%2FgpWFC/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/s-ol","download_url":"https://codeload.github.com/s-ol/gpWFC/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244146279,"owners_count":20405802,"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":["algorithm","gamedev","machine-learning","opencl","procedural-generation","python","wfc"],"created_at":"2024-10-12T06:06:31.666Z","updated_at":"2025-03-21T15:31:41.172Z","avatar_url":"https://github.com/s-ol.png","language":"Python","readme":"gpWFC\n=====\n\nImplementation of the [Wave Function Collapse][WFC] procedural content generation algorithm,\nusing [(py)OpenCL][pyopencl] for GPU acceleration.\n\n![circuit example](https://thumbs.gfycat.com/MinorFewBlackmamba-max-1mb.gif) ![simple  example](https://thumbs.gfycat.com/FinishedFlamboyantHylaeosaurus-max-1mb.gif)\n\nGetting Started\n---------------\n\nmake sure you have the python packages pyopencl, numpy and pyglet installed.\n\nYou can then run a basic example using\n\n    python main.py\n\nin the preview window the following keybindings are set:\n\n- `escape`: close\n- `space`: do one oberservation/propagation cycle and render\n- `r`: cycle until stable, then render again\n- `d`: debug view (overlay decimal display of bitmask for each tile)\n\nThere is also a more interesting sprite-based example that you can run using\n\n    python circuit.py [render]\n\nbut as you can see I didn't set up the model constraints properly. Maybe you want to fix that?\n\n`main.py` can take a few options that are just passed as strings on the command line, in any order.\nThey might not all be compatible with each other, in any case `main.py` is only a\nstarting point to write your own set up code with a more serious model.\n\n### `cpu`\n\npropagate using a simplistic CPU algorithm.\n\n### `3d`\n\nwork in a 3d space (4x4x2 by default), with a *very* rudimentary preview.\nmore of a proof of concept, but totally workable.\n\nIn the 3d preview, the up and down keys can be used to cycle through slices of the Z axis.\n\n### `silent`\n\ndon't open a preview or render, just measure the execution time.\n\n### `render`\n\nautomatically step execution forward and take save a screenshot to `shots/0001.png` etc.\nYou can use e.g. ffmpeg to turn the png frames into an animation.\n\nProgramatic Usage\n-----------------\n\n`gpWFC` is set up to follow a 'mix and match' modular architecture as best as possible.\nIt is therefore divided into a couple of components that need to be used to run a simulation:\n\n- the Tiles (`Tile` and `SpriteTile` from `models.py`):\n  - `tile.weight` (float): the relative probability of occurence\n  - `tile.compatible(other, direction_id)` (bool): constraint information\n  - additional information for the Preview, e.g. `tile.image` and `tile.rotation` for `SpriteTile`\n- the Model (`Model2d` and `Model3d` from `models.py`):\n  - information about the *world*:\n    - `model.world_shape` (tuple): dimensions of the world (any nr of axes)\n    - `model.get_neighbours(pos)` (generator): tile adjacency information\n  - information about the *tiles*:\n    - `model.tiles` (list): the tiles to be used\n    - `model.get_allowed_tiles(bitmask)` (list): a way to resolve the opaque bitmask\n- the Runner (`Runner` and `BacktrackingRunner` from `runners.py`):\n  - `runner.step()` (string): execute a single observartion/propagation cycle\n  - `runner.finish()` (string): run the simulation until it either fails or stabilizes\n  - `runner.run()` (generator): iterate over `runner.step()`\n  - all of these return/yield status strings, which are one of:\n    - `'done'` - fully collapsed\n    - `'error'` - overconstrained / stuck\n    - `'continue'` - step successful but uncollapsed tiles remain\n- the Preview (`PreviewWindow*` from `previews.py`):\n  - `preview.draw_tiles(pos, bits)`: draw the tiles at `pos` (tuple)\n  - `preview.launch()`: enter interactive preview mode\n  - `preview.render()`: enter non-interactive render loop\n- the Observer and Propagator (`observers.py` and `propagators.py`):\n  - you probably don't need to touch these\n\nYou can find a straightforward example of the basic setup steps in `circuit.py`, it should follow this flow:\n\n- instantiate a Model\n- instantiate Tiles and register them with the Model\n- instantiate a Runner and pass it the Model\n- instantiate a Preview and pass it the Runner\n- launch the Preview\n\nGPU-only rendering\n------------------\n\nThere is a terribly broken `glsl-render` branch that tries to not ever get the buffer back to CPU memory during propagation,\nwhile still rendering the world in a GLSL shader.\nUnfortunately I could never get it to work properly with pyOpenCL to date, and due to some other constraints\nI also cannot test or bring the current version back to the best state it was in,\nso it will remain in a messy test state for now.\n\nIf anyone is brave enough to touch it though, when working, it should give some incredible performance gains as the rendering\nand memory transfer / gpu blocking are by far the biggest slow-downs at the moment.\nThere is also some hope since a new version of pyOpenCL is [apparently on the way][opencl-fix].\n\n[WFC]: https://github.com/mxgmn/WaveFunctionCollapse\n[pyopencl]: https://documen.tician.de/pyopencl\n[opencl-fix]: https://github.com/inducer/pyopencl/issues/235#issuecomment-431644685\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs-ol%2Fgpwfc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fs-ol%2Fgpwfc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs-ol%2Fgpwfc/lists"}