{"id":18478348,"url":"https://github.com/robohouse-delft/show-image-rs","last_synced_at":"2025-04-04T17:05:30.182Z","repository":{"id":39904537,"uuid":"231630192","full_name":"robohouse-delft/show-image-rs","owner":"robohouse-delft","description":"Quickly show images for debugging in Rust.","archived":false,"fork":false,"pushed_at":"2025-03-09T10:54:28.000Z","size":661,"stargazers_count":41,"open_issues_count":8,"forks_count":12,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-28T16:06:05.808Z","etag":null,"topics":["debugging","gui","hacktoberfest","image","rust","window"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robohouse-delft.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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":"2020-01-03T17:02:44.000Z","updated_at":"2025-02-23T19:37:57.000Z","dependencies_parsed_at":"2024-12-21T09:06:44.186Z","dependency_job_id":"c2f30808-08cd-4a74-a205-632377c4a471","html_url":"https://github.com/robohouse-delft/show-image-rs","commit_stats":{"total_commits":396,"total_committers":10,"mean_commits":39.6,"dds":0.0757575757575758,"last_synced_commit":"9b271c72cdfd79888dc7fbb5b813804eec84c1c4"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robohouse-delft%2Fshow-image-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robohouse-delft%2Fshow-image-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robohouse-delft%2Fshow-image-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robohouse-delft%2Fshow-image-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robohouse-delft","download_url":"https://codeload.github.com/robohouse-delft/show-image-rs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247217174,"owners_count":20903008,"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":["debugging","gui","hacktoberfest","image","rust","window"],"created_at":"2024-11-06T12:09:46.615Z","updated_at":"2025-04-04T17:05:30.164Z","avatar_url":"https://github.com/robohouse-delft.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Docs.rs](https://docs.rs/show-image/badge.svg)](https://docs.rs/crate/show-image/)\n[![CI](https://github.com/robohouse-delft/show-image-rs/workflows/CI/badge.svg)](https://github.com/robohouse-delft/show-image-rs/actions?query=workflow%3ACI+branch%3Amain)\n\n# show-image\n\n`show-image` is a library for quickly displaying images.\nIt is intended as a debugging aid for writing image processing code.\nThe library is not intended for making full-featured GUIs,\nbut you can process keyboard events from the created windows.\n\n## Supported image types.\nThe library aims to support as many different data types used to represent images.\nTo keep the dependency graph as small as possible,\nsupport for third party libraries must be enabled explicitly with feature flags.\n\nCurrently, the following types are supported:\n  * The [`Image`] and [`ImageView`] types from this crate.\n  * [`image::DynamicImage`][::image::DynamicImage] and [`image::ImageBuffer`][::image::ImageBuffer] (requires the `\"image\"` feature).\n  * [`tch::Tensor`][::tch::Tensor] (requires the `\"tch\"` feature).\n  * [`raqote::DrawTarget`][::raqote::DrawTarget] and [`raqote::Image`][::raqote::Image] (requires the `\"raqote\"` feature).\n\nIf you think support for a some data type is missing,\nfeel free to send a PR or create an issue on GitHub.\n\n## Global context and threading\nThe library uses a global context that runs an event loop.\nThis context must be initialized before any `show-image` functions can be used.\nAdditionally, some platforms require the event loop to be run in the main thread.\nTo ensure portability, the same restriction is enforced on all platforms.\n\nThe easiest way to initialize the global context and run the event loop in the main thread\nis to use the [`main`] attribute macro on your main function.\nIf you want to run some code in the main thread before the global context takes over,\nyou can use the [`run_context()`] function or one of it's variations instead.\nNote that you must still call those functions from the main thread,\nand they do not return control back to the caller.\n\n## Event handling.\nYou can register an event handler to run in the global context thread using [`WindowProxy::add_event_handler()`] or some of the similar functions.\nYou can also register an event handler directly with the context to handle global events (including all window events).\nSince these event handlers run in the event loop, they should not block for any significant time.\n\nYou can also receive events using [`WindowProxy::event_channel()`] or [`ContextProxy::event_channel()`].\nThese functions create a new channel for receiving window events or global events, respectively.\nAs long as you're receiving the events in your own thread, you can block as long as you like.\n\n## Saving displayed images.\nIf the `save` feature is enabled, windows allow the displayed image to be saved using `Ctrl+S` or `Ctrl+Shift+S`.\nThe first shortcut will open a file dialog to save the currently displayed image.\nThe second shortcut will directly save the image in the current working directory using the name of the image.\n\nThe image is saved without any overlays.\nTo save an image including overlays, add `Alt` to the shortcut: `Ctrl+Alt+S` and `Ctrl+Alt+Shift+S`.\n\nNote that images are saved in a background thread.\nTo ensure that no data loss occurs, call [`exit()`] to terminate the process rather than [`std::process::exit()`].\nThat will ensure that the background threads are joined before the process is terminated.\n\n## Example 1: Showing an image.\n```rust\nuse show_image::{ImageView, ImageInfo, create_window};\n\n#[show_image::main]\nfn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n\n  let image = ImageView::new(ImageInfo::rgb8(1920, 1080), pixel_data);\n\n  // Create a window with default options and display the image.\n  let window = create_window(\"image\", Default::default())?;\n  window.set_image(\"image-001\", image)?;\n\n  Ok(())\n}\n```\n\n## Example 2: Handling keyboard events using an event channel.\n```rust\nuse show_image::{event, create_window};\n\n// Create a window and display the image.\nlet window = create_window(\"image\", Default::default())?;\nwindow.set_image(\"image-001\", \u0026image)?;\n\n// Print keyboard events until Escape is pressed, then exit.\n// If the user closes the window, the channel is closed and the loop also exits.\nfor event in window.event_channel()? {\n  if let event::WindowEvent::KeyboardInput(event) = event {\n        println!(\"{:#?}\", event);\n        if event.input.key_code == Some(event::VirtualKeyCode::Escape) \u0026\u0026 event.input.state.is_pressed() {\n            break;\n        }\n    }\n}\n\n```\n\n## Back-end and GPU selection\n\nThis crate uses [`wgpu`] for rendering.\nYou can force the selection of a specfic WGPU backend by setting the `WGPU_BACKEND` environment variable to one of the supported values:\n\n* `primary`: Use the primary backend for the platform (the default).\n* `vulkan`: Use the vulkan back-end.\n* `metal`: Use the metal back-end.\n* `dx12`: Use the DirectX 12 back-end.\n* `dx11`: Use the DirectX 11 back-end.\n* `gl`: Use the OpenGL back-end.\n* `webgpu`: Use the browser WebGPU back-end.\n\nYou can also influence the GPU selection by setting the `WGPU_POWER_PREF` environment variable:\n\n* `low`: Prefer a low power GPU (the default).\n* `high`: Prefer a high performance GPU.\n\n[`Image`]: https://docs.rs/show-image/latest/show_image/enum.Image.html\n[`ImageView`]: https://docs.rs/show-image/latest/show_image/struct.ImageView.html\n[::image::DynamicImage]: https://docs.rs/image/latest/image/dynimage/enum.DynamicImage.html\n[::image::ImageBuffer]: https://docs.rs/image/latest/image/buffer_/struct.ImageBuffer.html\n[::tch::Tensor]: https://docs.rs/tch/latest/tch/wrappers/tensor/struct.Tensor.html\n[::raqote::DrawTarget]: https://docs.rs/raqote/latest/raqote/struct.DrawTarget.html\n[::raqote::Image]: https://docs.rs/raqote/latest/raqote/struct.Image.html\n[`main`]: https://docs.rs/show-image/latest/show_image/attr.main.html\n[`run_context()`]: https://docs.rs/show-image/latest/show_image/fn.run_context.html\n[`WindowProxy::add_event_handler()`]: https://docs.rs/show-image/latest/show_image/struct.WindowProxy.html#method.add_event_handler\n[`WindowProxy::event_channel()`]: https://docs.rs/show-image/latest/show_image/struct.WindowProxy.html#method.event_channel\n[`ContextProxy::event_channel()`]: https://docs.rs/show-image/latest/show_image/struct.ContextProxy.html#method.event_channel\n[`exit()`]: https://docs.rs/show-image/latest/show_image/fn.exit.html\n[`std::process::exit()`]: https://doc.rust-lang.org/nightly/std/process/fn.exit.html\n[`wgpu`]: https://docs.rs/wgpu\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobohouse-delft%2Fshow-image-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobohouse-delft%2Fshow-image-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobohouse-delft%2Fshow-image-rs/lists"}