{"id":28050662,"url":"https://github.com/emsquid/pic","last_synced_at":"2025-05-12T00:38:12.724Z","repository":{"id":65576711,"uuid":"590606396","full_name":"emsquid/pic","owner":"emsquid","description":"Preview Image in CLI.","archived":false,"fork":false,"pushed_at":"2023-03-21T14:37:41.000Z","size":254627,"stargazers_count":60,"open_issues_count":4,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-12T00:38:09.834Z","etag":null,"topics":["command-line","rust","terminal"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/emsquid.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2023-01-18T19:47:09.000Z","updated_at":"2025-01-27T11:35:28.000Z","dependencies_parsed_at":"2023-02-16T05:46:02.381Z","dependency_job_id":"d3a2aae7-da3f-4ebd-bceb-23165e4a6976","html_url":"https://github.com/emsquid/pic","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/emsquid%2Fpic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emsquid%2Fpic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emsquid%2Fpic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emsquid%2Fpic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emsquid","download_url":"https://codeload.github.com/emsquid/pic/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253655914,"owners_count":21943072,"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":["command-line","rust","terminal"],"created_at":"2025-05-12T00:38:07.903Z","updated_at":"2025-05-12T00:38:12.701Z","avatar_url":"https://github.com/emsquid.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PIC 📷\n\nPIC (**P**review **I**mage in **C**LI ) is a lightweight Rust tool to preview images in your terminal!\n\u003cbr\u003e\nWith support for various image protocols ([`Kitty`](https://sw.kovidgoyal.net/kitty/graphics-protocol/), [`Sixel`](https://saitoha.github.io/libsixel/), [`iTerm`](https://iterm2.com/documentation-images.html)) it works in several terminals, and can still use Unicode blocks in case your terminal isn't supported.\nPIC also provides a library for you to use in your own tools!\n\n## Features\n\n- Choose your favourite protocols\n    * Kitty graphics with multiple actions available (`load`/`clear`)\n    * Sixel which works in a lot of terminals\n    * iTerm which displays GIFs incredibly well\n    * Unicode blocks with truecolor/ansi256 support otherwise\n- Customization\n    * `--x` and `--y` options to choose where to display your image\n    * `--cols` and `--rows` options to choose the size of your image (always tries preserving ratio)\n    * `--upscale` option to preview image at full wanted size if needed\n    * `--static` and `--loop` options to interact with GIFs\n    * `--protocol` option to choose a protocol\n    * `--load` `--display` and `--clear` options to interact with Kitty protocol\n\n## Installation\n\n### From source (Recommended)\n\nPrerequisites\n- [Git](https://git-scm.com/downloads)\n- [Rust toolchain](https://www.rust-lang.org/tools/install)\n\nCommand line instructions\n```bash\n# Clone the repository\ngit clone https://github.com/emsquid/pic\n\n# Build and install\ncargo install --path pic\n\n# Use freely\npic Images/YourFavouriteImage.png --cols 13 ...\n```\n\n### From Cargo\n\nPrerequisites\n- [Rust toolchain](https://www.rust-lang.org/tools/install)\n\nCommand line instructions\n```bash\n# Build and install\ncargo install pic\n\n# Use freely again\npic Images/YourFavouriteImage.png --cols 13 ...\n```\n\n### As a library\n\nPrerequisites\n- [Rust toolchain](https://www.rust-lang.org/tools/install)\n\nCommand line instructions\n```bash\n# Add the dependency in your project directory\ncargo add pic\n```\n\n## Examples\n\nBlocks \u0026 Top quality previewing\n\n![demo](examples/blocks.png)\n![demo](examples/top_quality.png)\n\nWide choice of options\n\n![options](examples/options.gif)\n\nReally nice GIFs in iTerm\n\n![iterm](examples/iterm.gif)\n\nAnd also nice in Blocks\n\n![gotcha](examples/blocks.gif)\n\n## Command line usage\n\n```\nPreview Image in CLI.\n\nUsage: pic [OPTIONS] [PATH]...\n\nArguments:\n  [PATH]...  Image(s) to preview\n\nOptions:\n  -p, --protocol \u003cPROTOCOL\u003e  Previewing protocol to use [possible values: kitty, sixel, iterm, blocks]\n  -x, --x \u003cX\u003e                x position (0 is left)\n  -y, --y \u003cY\u003e                y position (0 is top)\n  -c, --cols \u003cCOLS\u003e          Number of cols to fit the preview in\n  -r, --rows \u003cROWS\u003e          Number of rows to fit the preview in\n      --spacing \u003cSPACING\u003e    Spacing between images if more than one file is provided\n  -u, --upscale              Upscale image if needed\n  -n, --no-newline           Don't print newline after preview\n  -s, --static               Only show first frame of GIFs\n  -l, --loop                 Loop GIFs infinitely\n      --load \u003cID\u003e            Load image with the given id (kitty only)\n      --display \u003cID\u003e         Display image with the given id (kitty only)\n      --clear \u003cID\u003e           Clear image with the given id (0 for all) (kitty only)\n  -h, --help                 Print help\n  -V, --version              Print version\n```\n\n## Library usage \n\n```rust\nuse pic\n\nfn main() {\n    // Choose images to preview\n    let path1 = std::path::PathBuf::from(\"Picture/MyFavImage.png\");\n    let mut options = pic::options::Options::new(vec![path1]);\n\n    // Set your options\n    options.set_position(Some(10), None);\n    options.set_size(Some(50), Some(50));\n    options.upscale();\n\n    // Preview\n    if let Err(err) = pic::previewer::preview(\u0026mut std::io::stdout(), \u0026mut options) {\n        eprintln!(\"{err}\");\n    };\n}\n```\n\n## Notes \n\n- `Sixel` protocol may require [libsixel](https://github.com/saitoha/libsixel) to be installed\n- `iTerm` protocol always loop GIFs, except if `--static` is specified\n\n## Progress\n\nHelp would be greatly appreciated\n\n- Documentation\n    * [ ] Write a greater README\n    * [ ] Make releases/packages (publish on crates.io)\n- Protocols support\n    * [ ] Preview GIFs with Kitty protocol\n    * [x] Preview GIFs with Unicode blocks\n    * [ ] Work on handling transparency/GIFs with Sixel protocol (GIFs work but don't render well)\n    * [ ] Improve protocol support checking (need to test in various terminal)\n- Miscellaneous\n    * [ ] Implement caching somehow\n    * [ ] Show cooler error messages\n    * [ ] Write tests (I guess I need to do that...)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femsquid%2Fpic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femsquid%2Fpic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femsquid%2Fpic/lists"}