Hello World

Image Slicing

#emacs
#project

Table of Contents

In Emacs, displaying an image occupies one line regardless of its height. The movement over the image while navigating by lines can be quite frustrating.

Although pixel-scroll and iscroll have improved image movement to some extent.

I hope to move images in the same way as moving text, line by line.

So I created this package to horizontally slice the images referenced in the buffer into multiple images. In Emacs, only a portion of the original image is displayed on each line. Finally, the image can be moved line by line.

During the development process, I found org-sliced-images which was almost the same as my idea. And thanks to him for letting me know about insert-sliced-image in Emacs.

1. Prerequisites

curl: Used to download remote images.

1.1. Require Packages

  • org-element: Used to parse the buffer to retrieve all links.
  • image: Used to create an image object.
  • url-util : A utility for handling URL formats.

1.2. Install

  • clone the project in your own emacs configuration files directory, like:
  git clone [email protected]:ginqi7/image-slicing.git ~/.emacs.d/lisp/image-slicing
  • add the path to 'load-path'
  (add-to-list 'load-path (expand-file-name "~/.emacs.d/lisp/d/lisp/image-slicing"))

2. Configuration

Here are a few variables that can be used for configuration: 

(require 'image-slicing)

2.1. Variables

variable default value explain
image-slicing-download-concurrency 20 the maximum concurrency of images download
image-slicing-line-height-scale 2 how many line height an image slice occupies
image-slicing-max-width 700 the maximum width of images display
image-slicing-cursor-fringe-bitmaps '(left-fringe right-arrow warning) the Fringe Bitmaps indicator for the cursor position.1

2.2. EWW Config

  1. cancel the eww defualt image render.
(add-to-list 'shr-external-rendering-functions
             '(img . image-slicing-tag-img))
  1. Add image-slicing to eww-after-render-hook
(push #'image-slicing-mode eww-after-render-hook)

3. Features

  • image-slicing-mode: Automatically finds image links in the buffer and renders them as multiline display.
  • Asynchronous: Asynchronous download of remote images.
  • EWW: Support eww-mode

3.1. Supported Link Format

3.1.1. Org Link

  • [[url][tag]]
  • [[url]]

3.1.2. pure link

  • file:./hello.png
  • http://image.png

4. Example

5. Disadvantages

  • If there are many remote image links in the buffer, it will generate many temporary image files in the temporary system directory.
  • If the URL link is too short, the number of slices of the original image will be small, and the image line height will be large.
  • Only one buffer can be rendered at a time.

6. Todo List

  • Adapt nov

7. Development History

7.1. Dec 18, 2024

I find a similar package named org-sliced-images, so I study some code from it to make my code simpler.

In Emacs, we can display a part of an image by using ('display . (list (list 'slice x y dx dy) image)), without needing to actually slice the image using ImageMagick, so I remove the dependency about ImageMagick.

7.2. Dec 16, 2024

There have some issues in last version:

  1. There is slow when ImageMagick handle remote images.
  2. Though I will delete the placeholders when the user removes the overlays, there is still a risk of polluting the users' buffer.

So I use asynchronous processes to run ImageMagick, guaranteeing that it will not freeze Emacs. On the other hand, I removed the placeholder and just placed some overlays on the original URL text.

7.3. May 12, 2023

I got the idea to slice the image into many pieces, making Emacs display the pieces line by line.

  1. Use the CLI ImageMagick to slice images.
  2. Insert some special text like "#_#_@@_#_#" as placeholder, and put an overlay on that placeholder to show image pieces.

Footnotes:

1

Emacs Fringe Bitmaps

  • Next: Using Emacs Combine Anything