edluffy/hologram.nvim
github
1,199
22
23
30
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
- Ability to transfer .png format files and display at an arbitrary location in an nvim buffer.
- Retain image transparency when being displayed.
- 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?
- 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:
- Switch to bare C implementation for base64 image encoding.