README.md

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 🚧.

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.