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 ImageMagick package. Currently, 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-get-exif-data and image-dired-set-exif-data to work,
the command line tool exiftool is needed. It can be found here:
https://exiftool.org/. These two functions are, among other
things, used for writing comments to image files using
image-dired-thumbnail-set-image-description and to create
"unique" file names using image-dired-get-exif-file-name (used by
image-dired-copy-with-exif-file-name).
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 format.
* WARNING: The "database" format used might be changed so keep a
backup of image-dired-db-file when testing new versions.
* image-dired-display-image-mode does not support animation
TODO
====
* Support gallery creation when using per-directory thumbnail
storage.
* Some sort of auto-rotate function based on rotate info in the
EXIF data.
* 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.
* From thumbs.el: Add setroot function.
* From thumbs.el: Add image resizing, if useful (image-dired's automatic
"image fit" might be enough)
* From thumbs.el: Add the "modify" commands (emboss, negate,
monochrome etc).
* 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.
* Enhanced gallery creation with basic CSS-support and pagination
of tag pages with many pictures.
* Rewrite image-dired-modify-mark-on-thumb-original-file to be
less ugly.
* In some way keep track of buffers and windows and stuff so that
it works as the user expects.
* More/better documentation
Defined variables (73)
image-dired-append-when-browsing | Append thumbnails in thumbnail buffer when browsing. |
image-dired-cmd-create-standard-thumbnail-options | Options for creating thumbnails according to the Thumbnail Managing Standard. |
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-create-thumbnail-options | Options of command used to create thumbnail image. |
image-dired-cmd-create-thumbnail-program | Executable used to create thumbnail. |
image-dired-cmd-optipng-options | Arguments passed to ‘image-dired-cmd-optipng-program’. |
image-dired-cmd-optipng-program | The file name of the ‘optipng’ program. |
image-dired-cmd-pngcrush-options | Arguments for ‘image-dired-cmd-pngcrush-program’. |
image-dired-cmd-pngcrush-program | The file name of the ‘pngcrush’ program. |
image-dired-cmd-pngnq-options | Arguments to pass ‘image-dired-cmd-pngnq-program’. |
image-dired-cmd-pngnq-program | The file name of the ‘pngnq’ program. |
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-original-options | Arguments of command used to rotate original image. |
image-dired-cmd-rotate-original-program | Executable used to rotate original 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-cmd-write-exif-data-options | Arguments of command used to write EXIF data. |
image-dired-cmd-write-exif-data-program | Program used to write EXIF data to image. |
image-dired-db-file | Database file where file names and their associated tags are stored. |
image-dired-dir | Directory where thumbnail images are stored. |
image-dired-dired-disp-props | If non-nil, display properties for Dired file when browsing. |
image-dired-display-image-buffer | Where larger versions of the images are display. |
image-dired-display-image-mode-abbrev-table | Abbrev table for ‘image-dired-display-image-mode’. |
image-dired-display-image-mode-hook | Hook run after entering image-dired-image-display mode. |
image-dired-display-image-mode-map | Keymap for ‘image-dired-display-image-mode’. |
image-dired-display-image-mode-syntax-table | Syntax table for ‘image-dired-display-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 | Name of external viewer. |
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. |
image-dired-gallery-thumb-image-root-url | URL where the thumbnail images are to be found. |
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-minor-mode | Non-nil if Image-Dired minor mode is enabled. |
image-dired-minor-mode-hook | Hook run after entering or leaving ‘image-dired-minor-mode’. |
image-dired-minor-mode-map | Keymap for ‘image-dired-minor-mode’. |
image-dired-queue | List of items in the queue. |
image-dired-queue-active-jobs | Number of active jobs in ‘image-dired-queue’. |
image-dired-queue-active-limit | Maximum number of concurrent jobs permitted for generating images. |
image-dired-rotate-original-ask-before-overwrite | Confirm overwrite of original file after rotate operation. |
image-dired-saved-window-configuration | Saved window configuration. |
image-dired-show-all-from-dir-max-files | Maximum number of files to show using ‘image-dired-show-all-from-dir’ |
image-dired-slideshow-count | Keeping track on number of images in 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-tag-history | Variable holding the tag history. |
image-dired-temp-image-file | Name of temporary image file used by various commands. |
image-dired-temp-rotate-image-file | Temporary file for rotate operations. |
image-dired-thumb-height | Height of thumbnails, in pixels. |
image-dired-thumb-margin | Size of the margin around thumbnails. |
image-dired-thumb-relief | Size of button-like border around thumbnails. |
image-dired-thumb-size | Size of thumbnails, in pixels. |
image-dired-thumb-visible-marks | Make marks visible in thumbnail buffer. |
image-dired-thumb-width | Width of thumbnails, in pixels. |
image-dired-thumbnail-buffer | Image-Dired’s thumbnail buffer. |
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-line-up-map | Keymap for line-up commands in ‘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-mode-tag-map | Keymap for tag commands in ‘image-dired-thumbnail-mode’. |
image-dired-thumbnail-storage | How to store image-dired’s 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 tracking and mirroring. |
image-dired-widget-list | List to keep track of meta data in edit buffer. |
Defined functions (128)
Defined faces (1)
image-dired-thumb-mark | Background-color for marked images in thumbnail buffer. |