File: image-dired.el.html
BACKGROUND
==========
I needed a program to browse, organize and tag my pictures. I got
tired of the old gallery program I used as it did not allow
multi-file operations easily. Also, it put things out of my
control. Image viewing programs I tested did not allow multi-file
operations or did not do what I wanted it to.
So, I got the idea to use the wonderful functionality of Emacs and
dired to do it. It would allow me to do almost anything I wanted,
which is basically just to browse all my pictures in an easy way,
letting me manipulate and tag them in various ways. dired already
provide all the file handling and navigation facilities; I only
needed to add some functions to display the images.
I briefly tried out thumbs.el, and although it seemed more
powerful than this package, it did not work the way I wanted to. It
was too slow to create thumbnails of all files in a directory (I
currently keep all my 2000+ images in the same directory) and
browsing the thumbnail buffer was slow too. image-dired.el will not
create thumbnails until they are needed and the browsing is done
quickly and easily in Dired. I copied a great deal of ideas and
code from there though... :)
image-dired stores the thumbnail files in image-dired-dir(var)/image-dired-dir(fun)
using the file name format ORIGNAME.thumb.ORIGEXT. For example
~/.emacs.d/image-dired/myimage01.thumb.jpg. The "database" is for
now just a plain text file with the following format:
file-name-non-directory;comment:comment-text;tag1;tag2;tag3;...;tagN
PREREQUISITES
=============
* The GraphicsMagick or ImageMagick package; Image-Dired uses
whichever is available.
A) For GraphicsMagick, gm is used.
Find it here: http://www.graphicsmagick.org/
B) For ImageMagick, convert and mogrify are used.
Find it here: https://www.imagemagick.org.
* For non-lossy rotation of JPEG images, the JpegTRAN program is
needed.
* For image-dired-set-exif-data to work, the command line tool exiftool is
needed. It can be found here: https://exiftool.org/. This
function is, among other things, used for writing comments to
image files using image-dired-thumbnail-set-image-description.
USAGE
=====
This information has been moved to the manual. Type C-h r to open
the Emacs manual and go to the node Thumbnails by typing g
Image-Dired RET.
Quickstart: M-x image-dired RET DIRNAME RET
where DIRNAME is a directory containing image files.
LIMITATIONS
===========
* Supports all image formats that Emacs and convert supports, but
the thumbnails are hard-coded to JPEG or PNG format. It uses
JPEG by default, but can optionally follow the Thumbnail Managing
Standard (v0.9.0, Dec 2020), which mandates PNG. See the user
option image-dired-thumbnail-storage.
* WARNING: The "database" format used might be changed so keep a
backup of image-dired-tags-db-file when testing new versions.
TODO
====
* Investigate if it is possible to also write the tags to the image
files.
* From thumbs.el: Add an option for clean-up/max-size functionality
for thumbnail directory.
* Add image-dired-display-thumbs-ring and functions to cycle that. Find out
which is best, saving old batch just before inserting new, or
saving the current batch in the ring when inserting it. Adding
it probably needs rewriting image-dired-display-thumbs to be more general.
* Find some way of toggling on and off really nice keybindings in
Dired (for example, using C-n or <down> instead of C-S-n).
Richard suggested that we could keep C-t as prefix for
image-dired commands as it is currently not used in Dired. He
also suggested that dired-next-line and dired-previous-line
figure out if image-dired is enabled in the current buffer and,
if it is, call image-dired-dired-next-line and image-dired-dired-previous-line,
respectively. Update: This is partly done; some bindings have
now been added to Dired.
* In some way keep track of buffers and windows and stuff so that
it works as the user expects.
* More/better documentation.
Defined variables (51)
image-dired--slideshow-timer | Slideshow timer. |
image-dired-cmd-create-temp-image-options | Options of command used to create temporary image for display window. |
image-dired-cmd-create-temp-image-program | Executable used to create temporary image. |
image-dired-cmd-read-exif-data-options | Arguments of command used to read EXIF data. |
image-dired-cmd-read-exif-data-program | Program used to read EXIF data to image. |
image-dired-cmd-rotate-thumbnail-options | Arguments of command used to rotate thumbnail image. |
image-dired-cmd-rotate-thumbnail-program | Executable used to rotate thumbnail. |
image-dired-db-file | Database file where image-dired file names and associated tags are stored. |
image-dired-dir | Directory where thumbnail images are stored. |
image-dired-display-image-mode-map | Keymap for ‘image-dired-image-mode’. |
image-dired-display-properties-format | Display format for thumbnail properties. |
image-dired-display-window-height-correction | Number to be used to correct image display window height. |
image-dired-display-window-width-correction | Number to be used to correct image display window width. |
image-dired-external-viewer | Shell command to invoke the external image viewer program. |
image-dired-file-comment-list | List to store file comments. |
image-dired-file-tag-list | List to store file-tag structure. |
image-dired-gallery-dir | Directory to store generated gallery html pages. |
image-dired-gallery-hidden-tags | List of "hidden" tags. |
image-dired-gallery-image-root-url | URL where the full size images are to be found on your web server. |
image-dired-gallery-thumb-image-root-url | URL where the thumbnail images are to be found on your web server. |
image-dired-image-mode-abbrev-table | Abbrev table for ‘image-dired-image-mode’. |
image-dired-image-mode-hook | Hook run after entering ‘image-dired-image-mode’. |
image-dired-image-mode-map | Keymap for ‘image-dired-image-mode’. |
image-dired-image-mode-syntax-table | Syntax table for ‘image-dired-image-mode’. |
image-dired-line-up-method | Default method for line-up of thumbnails in thumbnail buffer. |
image-dired-main-image-directory | Name of main image directory, if any. |
image-dired-marking-shows-next | If non-nil, marking, unmarking or flagging an image shows the next image. |
image-dired-rotate-original-ask-before-overwrite | Confirm overwriting of original file after image-rotate operation. |
image-dired-saved-window-configuration | Saved window configuration. |
image-dired-show-all-from-dir-max-files | Maximum number of files in directory to show before prompting. |
image-dired-slideshow-count | Keeping track on number of images in slideshow. |
image-dired-slideshow-delay | Seconds to wait before showing the next image in a slideshow. |
image-dired-slideshow-timer | Slideshow timer. |
image-dired-slideshow-times | Number of pictures to display in slideshow. |
image-dired-tag-file-list | List to store tag-file structure. |
image-dired-tags-db-file | Database file where image-dired file names and associated tags are stored. |
image-dired-temp-image-file | Name of temporary image file used by various commands. |
image-dired-thumb-height | Height of thumbnails, in pixels. |
image-dired-thumb-margin | Size of the margin around thumbnails. |
image-dired-thumb-naming | How ‘image-dired’ names thumbnail files. |
image-dired-thumb-relief | Size of button-like border around thumbnails. |
image-dired-thumb-size | Default size of thumbnails in pixels. |
image-dired-thumb-visible-marks | Make marks and flags visible in thumbnail buffer. |
image-dired-thumb-width | Width of thumbnails, in pixels. |
image-dired-thumbnail-mode-abbrev-table | Abbrev table for ‘image-dired-thumbnail-mode’. |
image-dired-thumbnail-mode-hook | Hook run after entering ‘image-dired-thumbnail-mode’. |
image-dired-thumbnail-mode-map | Keymap for ‘image-dired-thumbnail-mode’. |
image-dired-thumbnail-mode-syntax-table | Syntax table for ‘image-dired-thumbnail-mode’. |
image-dired-thumbnail-storage | Where ‘image-dired’ stores thumbnail files. |
image-dired-thumbs-per-row | Number of thumbnails to display per row in thumb buffer. |
image-dired-track-movement | The current state of the Image-Dired tracking and mirroring of thumbnails. |
Defined functions (105)
Defined faces (6)
image-dired-thumb-flagged | Face for images flagged for deletion in thumbnail buffer. |
image-dired-thumb-header-directory-name | Face for the directory name in the header line of the thumbnail buffer. |
image-dired-thumb-header-file-name | Face for the file name in the header line of the thumbnail buffer. |
image-dired-thumb-header-file-size | Face for the file size in the header line of the thumbnail buffer. |
image-dired-thumb-header-image-count | Face for the image count in the header line of the thumbnail buffer. |
image-dired-thumb-mark | Face for marked images in thumbnail buffer. |