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

Using packer.nvim:

use {'edluffy/hologram.nvim'}

Using vim-plug:

Plug 'edluffy/hologram.nvim'

Usage

Hologram.nvim allows you to view inline images directly inside a Neovim buffer. Requires the following setup in init.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 :luafile %:

local source = '/Users/.../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.

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.

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.

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
- [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.
- [ ] Extend to work with file formats other than png, like jpg.
- [ ] Add more transmission mediums apart from direct (data is transmitted within escape code itself), e.g files and temporary files - add download and display image from url?
- [x] Auto crop image when partly out of bounds.
- [ ] Ability to transfer animation frame data.
[ ] Support for Iterm2 Images Protocol.
(potential) Support for Sixel format.
Extend to work with tmux - 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.

edluffy / hologram.nvim

readme