{"id":29274808,"url":"https://github.com/heyoeyo/toadui","last_synced_at":"2026-05-01T12:33:13.994Z","repository":{"id":302521541,"uuid":"1011460885","full_name":"heyoeyo/toadui","owner":"heyoeyo","description":"A UI library, with warts!","archived":false,"fork":false,"pushed_at":"2025-07-27T16:57:45.000Z","size":250,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-27T18:54:54.306Z","etag":null,"topics":["gui","library","opencv","python","ui"],"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/heyoeyo.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,"zenodo":null}},"created_at":"2025-06-30T21:18:48.000Z","updated_at":"2025-07-27T16:57:48.000Z","dependencies_parsed_at":"2025-07-02T21:24:49.187Z","dependency_job_id":"45585e58-5e88-4af1-8ded-dfbfa19d65db","html_url":"https://github.com/heyoeyo/toadui","commit_stats":null,"previous_names":["heyoeyo/toadui"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/heyoeyo/toadui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heyoeyo%2Ftoadui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heyoeyo%2Ftoadui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heyoeyo%2Ftoadui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heyoeyo%2Ftoadui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heyoeyo","download_url":"https://codeload.github.com/heyoeyo/toadui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heyoeyo%2Ftoadui/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268378470,"owners_count":24240894,"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","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["gui","library","opencv","python","ui"],"created_at":"2025-07-05T05:00:41.869Z","updated_at":"2026-05-01T12:33:13.983Z","avatar_url":"https://github.com/heyoeyo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ToadUI\n\nToadUI is a helper UI library, written in Python, built on top of the basic UI provided by [OpenCV](https://opencv.org/). As such, it inherits much of the UI limitations of OpenCV but also it's ease of use. The goal is to provide ready-to-use UI elements that are not already part of OpenCV (e.g. buttons), while remaining easily compatible with existing code that uses OpenCV and/or [NumPy](https://numpy.org/).\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/285c9cfa-1a4e-4347-bb1f-1b8bf4a1a242\"\u003e\n\u003c/p\u003e\n\nCheck out the [demos](https://github.com/heyoeyo/toadui/tree/main/demos) to see what can be done with ToadUI.\n\n\u003e [!IMPORTANT]\n\u003e This library is still in early development, expect breaking changes as the structure of the library stabilizes\n\n\n## Who is this for?\n\nThis library is intended for prototyping and is geared towards handling video (or video-like) visualizations. Any data that can be converted to a 2D NumPy array is suitable. For example, earlier versions of the library have been used to interactively visualize the internal state of vision transformer models (see experiments from [MuggledDPT](https://github.com/heyoeyo/muggled_dpt/tree/main/experiments) and [MuggledSAM](https://github.com/heyoeyo/muggled_sam/tree/main/experiments)).\n\n\n### Basic features\n\n- Stacking/tiling style layout. No need to position anything\n- Built-in support for basic elements (buttons, toggles, sliders etc.)\n- Built-in support for basic video playback/control\n- Built-in support for colormapping (useful for data visualization)\n- Built-in support for point/box/polygon drawing (e.g. ROI selection)\n\n### Better than XYZ alternative?\n\nIf you're looking to make a UI for a _product_, ToadUI probably isn't suitable!\n\nThis library is mainly recommended for those who are already using OpenCV, or for exploratory data analysis. It's not meant for making professional or consumer-facing UIs. It's also poorly suited to anything requiring text input from users, at least for now.\n\n\n\n## Installation\n\nToadUI is still in early development and is therefore not recommended for projects requiring stability. However, it can be installed using pip or uv if you would like to experiment with it. It can be installed into an existing project using Github:\n\n\u003cdetails\u003e\n\u003csummary\u003eUsing pip\u003c/summary\u003e\n\n### Install using pip:\n\nAfter [cloning this repo](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository), make sure to create a [virtual environment](https://docs.python.org/3/library/venv.html), using:\n```bash\n# For linux or mac:\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# For windows (cmd):\npython -m venv .venv\n.venv\\Scripts\\activate\n```\nAnd then install in [editable mode](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs) using:\n```bash\npip install -e .\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eUsing uv\u003c/summary\u003e\n\n### Install using uv:\n\nIf you prefer to use something like [uv](https://docs.astral.sh/uv/) to install the project, then after cloning the repo you can simply run something like:\n```bash\nuv run demos/game_of_life.py\n```\nWhich will install the project and run one of the included demos.\n\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n\u003csummary\u003eInstall from Github\u003c/summary\u003e\n\n### Installing from github:\n\nThis repo can be installed into an existing project by using github:\n\n#### Using pip:\n```bash\n# Be sure to activate a virtual environment before installing!\npip install git+https://github.com/heyoeyo/toadui\n```\n\n#### Using UV:\n```bash\nuv venv \u0026\u0026 uv pip install git+https://github.com/heyoeyo/toadui\n```\n\u003c/details\u003e\n\n## Usage\n\nToadUI uses a hybrid system that blends concepts from both [retained mode](https://en.wikipedia.org/wiki/Retained_mode) and [immediate mode](https://en.wikipedia.org/wiki/Immediate_mode_(computer_graphics)) design. As a user of the library, this means you define the structure and layout of your UI elements ahead of time (a bit like HTML), but interactions and rendering are handled in a synchronous, on-demand way. This isn't particularly efficient, but lends itself to code that's easy to write.\n\n### Simple Example\n\nThe following example creates a UI for a simple video player:\n\n```python\nimport toadui as tui\n\nvreader = tui.LoopingVideoReader(\"/path/to/video.mp4\")\n\n# Define UI elements\nimg_elem = tui.DynamicImage()\nplayback_slider = tui.VideoPlaybackSlider(vreader)\nui_layout = tui.VStack(img_elem, playback_slider)\n\n# Set up display window and attach UI for mouse interactions\nwindow = tui.DisplayWindow(display_fps=vreader.get_framerate())\nwindow.attach_mouse_callbacks(ui_layout)\nwindow.attach_one_keypress_callback(\"spacebar\", vreader.toggle_pause)\n\nwhile True:\n    is_paused, frame_idx, frame = vreader.read()\n    playback_slider.update_state(is_paused, frame_idx)\n\n    # Update displayed image \u0026 render\n    img_elem.set_image(frame)\n    display_image = ui_layout.render(h=800)\n    req_break, keypress = window.show(display_image)\n    if req_break:\n        break\n\n# Clean up\nvreader.release()\nwindow.close()\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/33ab98ba-71a6-43fb-b247-e66e33b37baa\" style=\"width:400px\"\u003e\n\u003c/p\u003e\n\nThe result is a simple video player with playback control via click-and-drag. The video can be paused/unpaused by pressing the spacebar or the included button next to the playback slider. A slightly more sophisticated implementation can be found in the [demos](https://github.com/heyoeyo/toadui/tree/main/demos#video_playbackpy).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheyoeyo%2Ftoadui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheyoeyo%2Ftoadui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheyoeyo%2Ftoadui/lists"}