Throughout macOS, objects like files, folders and apps are displayed as icons, which are managed and delivered by Icon Services. Although many of those are generic to that class of object, the Finder and many apps use thumbnail images to represent specific objects. Zip archives and Installer packages are denoted by type-specific icons, images by individual thumbnails, and text files can use either depending on their context. In addition to those, the Finder and some apps can display the rendered contents of some types of file in previews, providing more detail and features such as annotation and text recognition.

Custom thumbnails and previews are the product of the QuickLook subsystem, and this article explains how they’re provided to Icon Services, here for use by the Finder, although the same mechanisms are available to other apps.

Caches

The success of Icon Services depends on speed of delivery as well as providing icons that are as faithful as possible for their size. Speed is achieved by maintaining a Thumbnail Cache containing those icons most likely to be needed, the primary purpose of iconservicesd. That cache is divided between memory and multiple locations on disk. The latter include a main store locked away from all access at /Library/Caches/com.apple.iconservices.store, and com.apple.iconservices and com.apple.dock.iconcache databases in private/var/folders/[2 chars]/…/C/, where … is a long alphanumeric name.

Generation

Fidelity of custom thumbnails and previews is ensured by many generators specific to the types of data to be rendered. There are currently a total of 19 bundled in macOS, in /System/Library/QuickLook, each of which will generate both thumbnails and previews. Data types are specified by UTI, thus PDF files with the UTI of com.adobe.pdf are handled by PDF.qlgenerator, while iWork.qlgenerator handles 15 different UTI types for documents written by Keynote, Numbers and Pages.

Custom UTI types that aren’t handled by any of those bundled qlgenerators can be turned into thumbnails and previews by appexes supplied by third-party app bundles. For example, Scapple documents with the UTI com.literatureandlatte.scapple.scap can have thumbnails generated by ScappleThumbnail.appex, while ScapplePreview.appex will generate previews for them. Both appexes are supplied in the Scapple app’s PlugIns folder inside the app’s bundle, as has been expected in recent macOS.

Selection of generator takes advantage of the hierarchical structure of UTIs. QuickLook’s dictionary of UTIs supported by generators normally contains no entry for the UTI public.jpeg, the most specific UTI for JPEG images, but it does for public.image, the more general type that public.jpeg conforms to. In the absence of a more specific generator, QuickLook uses Image.qlgenerator to produce thumbnails for JPEG images. This allows a third party to implement a better generator for JPEG images using their public.jpeg UTI, rather than public.image. The same is used by PreviewCode to generate thumbnails and previews of Swift source code using its specific UTI of public.swift-source, while the macOS Text.qlgenerator goes no more specific than public.plain-text, to which public.swift-source conforms.

QuickLook offers two strategies for generating thumbnails:

• Best possible quality, which may take significant time to create large thumbnail images from large original files.
• Multiple resolutions, which creates low resolution images quickly, then replaces them with higher resolution when it can.

You can see the latter in action sometimes when thumbnails are being generated for large Gallery view windows in the Finder.

App and bundle thumbnails

In contrast to files, app- and bundle-specific icons aren’t generated from file data, but taken from an icon located in the bundle’s Resources. When first viewed in a Finder window, if app icons haven’t already been cached, they will initially be displayed using placeholder icons. Each app is then looked up by LaunchServices in its records, and Icon Services adds its icon to the app icon section of the Thumbnail Cache.

Placeholder icons

When there’s a delay in generating or fetching a file’s specific icon, a placeholder icon is used by Icon Services instead. These are specific to the UTI type of that file, and will remain if no more specific icon can be generated.

Placeholders are used permanently for file types which don’t have specific content-based thumbnails generated for them, such as Apple Archives with the extension aar, with a UTI of com.apple.archive. The icon displayed is then based on that for public.archive, with the letters AAR added to indicate they’re Apple Archives.

Placeholders are also used in other circumstances. A common example is for text files listed in a Finder Column view, where all files with the UTI of public.plain-text are displayed using a generic icon, although they’re shown in the Preview pane as a fully rendered preview. The same applies to Rich Text files with a UTI of public.rtf, which use the same Text.qlgenerator, but not for PDF files.

QuickLook providing a thumbnail

To cover the range of actions more fully, this account is a composite based on what happens when you open a folder in the Finder’s column view, extending to cover the principles for the display of contents in a Preview pane.

The initial request from the Finder is to retrieve the icon from the Thumbnail Cache. If it’s not found there, what happens next depends on what the icon represents.

For app and similar bundle icons, LaunchServices searches app records, the icon is found, and Icon Services add it as a new indexed store entry.

For files, if it already has a placeholder image, as a type icon, and its contents can be rendered into a thumbnail, QuickLook UI will create and load a QLPreviewDocument such as a QLTextDisplayBundle, for the Finder to display in the Preview pane.

Otherwise the Thumbnailing Daemon queues a thumbnail request. First the memory cache is checked, then the disk cache. If the thumbnail can’t be found in those, then a new thumbnail is generated locally for that file. The first step in that process is for QuickLook Support to check the file’s UTI, and ascend through the UTIs that conforms to, as its more generic types. This determines which generator will be called to generate the thumbnail image. If that fails to generate an image, the Thumbnailing Daemon will generate that deemed ‘most representative’, usually a placeholder icon.

The generated icon is then added as a new store entry and indexed by Icon Services, and that’s written from the memory cache to the disk cache.

This is summarised in the following diagram.

available here as a PDF: QuickLook265a

References

Apple’s developer docs on QuickLook thumbnailing.
Apple’s developer docs on QuickLook preview generation
Apple’s Developer docs on QuickLook UI and previews