Awesome

Install

To work properly, hologram.nvim requires that the magick luarock is installed and readily available on your system.

Using packer.nvim:

use {
    'edluffy/hologram.nvim',
    config = function()
        require("hologram").setup()
    end,

    rocks = { "magick" },
}

Using vim-plug:

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:

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-version>/<package-name>:

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:

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 %:

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.

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, webp and others.
  • Add download from URL and send to terminal functionality.
  • 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.

Known Limitations

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