KittyTerminalImages.jl
Description
A package that allows Julia to display images in the kitty terminal editor.
Screenshots
 Colors.jl |
 Images.jl |
 Plots.jl |
 Luxor.jl |
 JuliaGraphs |
Installation
KittyTerminalImages.jl can be installed from the package manager by typing the following to your REPL:
] add KittyTerminalImagesIn addition you will need install the Kitty terminal emulator. It works on macOS or Linux but (at least currently) not on Windows. You can get it here: https://github.com/kovidgoyal/kitty
Usage
Simple load KittyTerminalImages in your REPL (assuming that you have opened Julia in kitty)
using KittyTerminalImagesSometimes when loading another package, such as Plots.jl or Gadfly.jl, they will put their own method for displaying images in an external program on the display stack, thus overriding the behaviour of KittyTerminalImages. To put KittyTerminalImages back on top of the stack, execute the following:
pushKittyDisplay!()You can also override the general display behaviour so KittyTerminalImages is on top of the stack. This is a hack and can have unwanted side effects. To do that, execute the following:
forceKittyDisplay!()Makie
It is possible to use Makie.jl together with KittyTerminalImages although there is no interactivity nor any animations.
After loading a Makie backend it might be necessary to run AbstractPlotting.inline!(true) so that the plots are shown in the terminal instead
of an external window. In my experience that is necessary for the GLMakie.jl backend
but not for the CairoMakie.jl backend.
Running scripts
Beware that KittyTerminalImages.jl relies on the display function to draw the plots, and this is not called automatically
when you are writing a script, unless the plotting command is the very last command in the script. If you want to force the
display of a plot, you can wrap the call with display:
# This is a script named "test.jl"
using Plots
using KittyTerminalImages
println("Here is the first plot:")
# We call "display" on plot's return value
plot(sin, 0:0.1:2Ο) |> display
println() # Force a newline
# Another plot
println("Here is another plot:")
plot(exp, 0:0.1:1)
plot!(log, 0.1:0.1:1) |> display # Only call "display" on the last "plot!"
println() # Force a newline
println("End of the script")The calls to display will make the plot appear when you run the script calling julia test.jl from the shell or writing
include("test.jl") in the REPL.
Configuration
Setting the scale
If the images are too small or too large for your terminal, you can specify a scale
set_kitty_config!(:scale, 2.0) # scale all images by a factor 2Setting preference for PNG or SVG
Certain Julia objects can be drawn as either a PNG or a SVG image. In case both formats are possible,
one can specify that PNG should be preferred by setting the :prefer_png_to_svg config value:
set_kitty_config!(:prefer_png_to_svg, true)At the moment this value is set to true by default as in some cases the svg renderer creates some incorrect images.
If the :scale config is also set, this has the disadvantage that scaled images may appear blurry.
Setting the transfer mode
To transfer the image from Julia to kitty, one can select between two transfer modes:
:direct(default) -- transfer the imagine with escape sequences:temp_file-- transfer the imagine by writing it to a temporary file and then transfer only the path of that image
Only :direct works if Julia is accessed remotely with SSH but if Julia is on the same machine as kitty then one might switch to :temp_file which might be slightly faster.
To switch the mode one can do
set_kitty_config!(:transfer_mode, :temp_file)Features
KittyTerminalImages can display all data types than can be converted to either PNG or SVG.
Limitations
- There are currently some unresolved issues with some SVG images.
- Does not work with tmux or screen yet.
- Can only display static images, there is no interaction.
- There might be some problems with some Julia packages. If that is the case, feel free to open an issue or submit a PR with a fix.
TODO list
- Display LaTeX images.
- Support for SSH.
- Support for tmux and screen.
- Add an option for setting the image output size.
- Query for the terminal size and colors.
- Allow specifying placement of the images - if possible have a mode where the terminal is split into a text and an image section.
- Figure out if it possible to play animations.