Skip to content

๐Ÿฎ a mini image viewer library and cli for testing programs which work with images

License

Notifications You must be signed in to change notification settings

foresterre/miniview

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

github crates.io ci docs-rs

miniview

MiniView is a bare-bones image viewer intended to be used during development and testing. MiniView can be called as binary from the CLI, and used as a Rust library.

To see what it can do, and whether it would fit your purpose, please see:

MiniView is not intended to be used as your primary image viewer. For that purpose, I would recommend Emulsion.

Install

Binary installation

With cargo install: cargo install miniview

Pre-build binary: see releases

Add library dependency

Run cargo add miniview with cargo-edit, or add miniview as a dependency to your Cargo.toml:

miniview = "*" # replace `*` with the latest version

Usage

Instructions for CLI use

Usage Linux example Windows example (cmd.exe)
miniview <PATH_TO_IMAGE> miniview image.png miniview image.png
miniview --from-path <PATH_TO_IMAGE> miniview --from-path image.png miniview --from-path image.png
miniview --from-stdin-path echo image.png | miniview --from-stdin-path echo image.png | miniview --from-stdin-path
miniview --from-stdin-bytes cat image.png | miniview --from-stdin-bytes type image.png | miniview --from-stdin-bytes

Flags & Options

Flag/Option Description
--fullscreen Set the window to fullscreen
--allow-window-resizing Allow the window to resize (doesn't resize the image!)
--close-after <n> Close the window after n milliseconds

Keyboard shortcuts

Press ESC to exit the image window.

Instructions for library use

use miniview::config::ConfigBuilder;
use std::time::Duration;

fn main() {
    let config =
        ConfigBuilder::from_path(concat!(env!("CARGO_MANIFEST_DIR"), "/resources/plant.jpg"))
            .set_fullscreen(true)
            .set_lazy_window(false)
            .build();

    let controls = MiniView::show(config).expect("unable to create miniview");

    // do some important other work!
    std::thread::sleep(Duration::from_millis(1000));

    let closed = controls.close();
    assert!(closed.is_ok());
}

Backends

MiniView supports two backends: piston-window and pixels. You can switch between backends on compile time. This requires setting Cargo features. The piston-window backend can be enabled using the backend_piston_window feature, and the pixels backend can be enabled using the backend_pixels feature.

The default backend is pixels. This backend will be used if no-default-features is not specified. Note that the default backend is not available on MacOS.

The next sections provide examples, on how to enable each backend. Only one backend should be enabled at a time.

backend: piston-window

Platform support

Platform Supported Tested Notes
Linux โœ… โœ…
MacOS MacOS does not allow the creation of graphical windows off the main thread.
Windows โœ… โœ…
... other piston-window + glutin platforms โœ… Assuming graphical windows can be created off the main thread.

Configuration examples

When building MiniView, the piston-window backend can be used by compiling with:

cargo run --no-default-features --features backend_piston_window 

When using MiniView as a library, you can use:

[dependencies.miniview]
version = "*" # replace `*` with the latest version
default-features = false 
features = ["backend_piston_window"]

or

[dependencies]
miniview = { version = "*", default-features = false, features = ["backend_piston_window"] }

NB: replace * in version = "*" with any supported version.

backend: pixels

Platform support

Platform Supported Tested Notes
Linux โœ… โœ…
Windows โœ… โœ…
MacOS MacOS does not allow the creation of graphical windows off the main thread.
FreeBSD โœ…
DragonflyBSD โœ…
NetBSD โœ…
OpenBSD โœ…
... other pixels + winit platforms Assuming graphical windows can be created off the main thread, support can be added. Please open an issue.

Configuration examples

When building MiniView, the pixels backend can be used by compiling with:

cargo run --no-default-features --features backend_pixels

When using MiniView as a library, you can use:

[dependencies.miniview]
version = "*" # replace `*` with the latest version
default-features = false 
features = ["backend_pixels"]

or

[dependencies]
miniview = { version = "*", default-features = false, features = ["backend_pixels"] }

NB: replace * in version = "*" with any supported version.

Suggestions, Questions, Bugs

Feel free to open an issue ๐Ÿ“ฌ if you have a suggestion, a question or found a bug =).

๐ŸŽธ ๐ŸŽบ ๐ŸŽป ๐ŸŽท