Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/vhyrro/hologram.nvim

👻 A cross platform terminal image viewer for Neovim. Extensible and fast, written in Lua and C. Works on macOS and Linux.
https://github.com/vhyrro/hologram.nvim

Last synced: 27 days ago
JSON representation

👻 A cross platform terminal image viewer for Neovim. Extensible and fast, written in Lua and C. Works on macOS and Linux.

Lists

README 

        


    hologram.nvim






    A cross platform terminal image viewer for Neovim. Extensible and fast, written in Lua and C.


    Works on macOS and Linux with current support for Kitty Graphics Protocol.


    Highly experimental, expect breaking changes 🚧.






  showcase




# Install



To work properly, `hologram.nvim` requires that the `magick` luarock is installed and

readily available on your system.



Using [packer.nvim](https://github.com/wbthomason/packer.nvim):

```lua

use {

    'edluffy/hologram.nvim',

    config = function()

        require("hologram").setup()

    end,



    rocks = { "magick" },

}

```

Using [vim-plug](https://github.com/junegunn/vim-plug):

```vimscript

Plug 'edluffy/hologram.nvim'

```



## Manual LuaRocks Installation



In case you are using a plugin manager that does not have luarocks integration,

you can opt to install `magick` manually by running the following command on your

system:



```sh

luarocks --local --lua-version=5.1 install magick

```



Afterwards, somewhere in the beginning of your Neovim configuration,

allow Lua to require installed `luarocks` packages. Usually you'll

find these plugins installed under `~/.luarocks/share/lua//`:



```lua

package.path = package.path .. ";~/.luarocks.share/lua/5.1/?/init.lua;"

```



# Usage



Hologram.nvim allows you to view inline images directly inside a Neovim buffer.

Requires the following setup in `init.lua`:



```lua

require('hologram').setup{

    auto_display = true -- WIP automatic markdown image display, may be prone to breaking

}

```



# Exposed API

There are plans for parts of Hologram to be able to be used in other plugins, such as its image functionality.



## `image.lua`

Minimal example - save as a file (e.g. minimal.lua) then run with `:so %`:



```lua

local source = '~/Documents/my-image.png'

local buf = vim.api.nvim_get_current_buf()

local image = require('hologram.image'):new(source, {})



-- Image should appear below this line, then disappear after 5 seconds



image:display(5, 0, buf, {})



vim.defer_fn(function()

    image:delete(0, {free = true})

end, 5000)

```



#### `Image:new(source, keys)`

Creates a new image object and sends image data with transmission keys to terminal.

```lua

Image:new(source, {

    format = 100, -- format in which image data is sent

    transmission_type = 'f', -- transmission medium used

    data_width = nil, -- px. width of image

    data_height = nil, -- px. height of image

    data_size = nil, -- size of data to read from file

    data_offset = nil, -- offset from which to read file data

    image_number = nil, -- image number

    compressed = nil, -- whether data is compressed or not

    image_id = nil, -- image id

    placement_id = 1, -- placement id

})

```

For more details see https://sw.kovidgoyal.net/kitty/graphics-protocol/#control-data-reference



#### `Image:display(row, col, buf, keys)`

Every image can be displayed an arbitrary number of times on the screen, with different adjustments applied. 

These operations do not require the re-transmission of image data and are as a result very fast and lightweight.

There should be no flicker or delay after an adjustment is made.

```lua

Image:display(row, col, buf, {

    x_offset = nil, -- left edge of image area to start displaying from (px.)

    y_offset = nil, -- top edge of image area to start displaying from (px.)

    width = nil, -- width of image area to display

    height = nil, -- height of image area to display

    cell_x = nil, -- x-offset within first cell to start displaying from (px.)

    cell_y = nil, -- y-offset within first cell to start displaying from (px.)

    cols = nil, -- number of columns to display over

    rows = nil, -- number of rows to display over

    z_index = 0, -- vertical stacking order of image

    placement_id = 1, -- placement id

})

```



#### `Image:delete(buf, opts)`



Deletes the image located in `buf`.



```lua

Image:delete(id, {

    free = false -- when deleting image, free stored image data and also extmark of image. (default: false)

})

```



# Roadmap

Core functionality:

- [ ] Support for [Kitty Graphics Protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol.html)

    - [x] Ability to transfer .png format files and display at an arbitrary location in an nvim buffer.

    - [x] Retain image transparency when being displayed.

    - [x] Retain image position when scrolling.

    - [x] Extend to work with file formats other than png, like jpg, webp and others.

    - [ ] Add download from URL and send to terminal functionality.

    - [x] Auto crop image when partly out of bounds.

    - [ ] Ability to transfer animation frame data.

- [ ] Support for [Iterm2 Images Protocol](https://iterm2.com/documentation-images.html#:~:text=Inline%20Images%20Protocol-,Inline%20Images%20Protocol,8%2Dbit%2Dclean%20environment).

- (potential) Support for Sixel format.

- Extend to work with [tmux](https://github.com/tmux/tmux/wiki) - wrap with DCS passthrough sequences?



Extensions:

- [ ] Floating image preview for .pdf, .md and .tex.

- [ ] Live file preview for .pdf and .md (using window splits).

- [ ] Live equation preview for .tex format.



Misc:

- [x] Switch to bare C implementation for base64 image encoding.



# Known Limitations

- [ ] Virtual lines other than the ones produced by hologram are not accounted for when placing an image.