krita/integration/README.md

0001 # Krita's macOS integration
0002
0003 This Xcode project generates QuickLook (macOS < 10.15), QuickLook Thumbnailing
0004 (macOS 10.15+) and Spotlight plugins for .kra and .ora files.
0005
0006 The QuickLook plugins take the `preview.png` image in the root of the ZIP
0007 container and use it as the thumbnail image, and the `mergedimage.png` file as
0008 the preview image. On files created with older versions of Krita that do not
0009 have `mergedimage.png`, QuickLook will simply fall back to using the thumbnail
0010 image instead.
0011
0012 The Spotlight plugin extracts the following metadata from the kra file, if
0013 available:
0014 - image dimensions, DPI, bit depth, and color space
0015 - color space profile name (not the actual name, as it's not embedded in the container; only the file path)
0016 - layer names
0017 - authors, image title and description
0018
0019 # Installing
0020
0021 Compile the project using Xcode or the provided CMake file. Find the build
0022 output folder (depends on how you configured the project), and place:
0023 - `kritaquicklook.qlgenerator` inside `~/Library/QuickLook`
0024 - `kritaspotlight.mdimporter` inside `~/Library/Spotlight`.
0025
0026 You can also place them in the system folders (`/Library/QuickLook` and
0027 `/Library/Spotlight` respectively). Test that they have been properly installed
0028 with:
0029 - QuickLook: `qlmanage -d2 -p <path to a kra file>; qlmanage -d2 -t <path to a kra file>`
0030 - Spotlight: `mdimport -d2 -t <path to a kra file>`
0031
0032 Be sure to reset QuickLook with `qlmanage -r` and `qlmanage -r cache`. If the
0033 changes don't happen right away, `killall Finder`.
0034
0035 **NOTE 1:** `kritaquicklookng.appex` **cannot be used standalone. You must bundle it with Krita (see below).**
0036
0037 **NOTE 2:** If you have krita installed to `/Applications`, Quicklook will always find
0038 first `kritaquicklook.qlgenerator` from `/Applications/krita.app` application
0039 bundle.
0040
0041 # Bundling
0042
0043 If you package Krita, place:
0044 - `kritaquicklook.qlgenerator` inside `krita.app/Contents/Library/QuickLook`
0045 - `kritaspotlight.mdimporter` inside `krita.app/Contents/Library/Spotlight`
0046 - `kritaquicklookng.appex` inside `krita.app/Contents/Library/PlugIns`
0047 Ensure the app is defined as the default app for opening .kra and .ora files,
0048 and codesign it whole if necessary.
0049
0050 # Hacking
0051 After applying changes and compiling, test your changes as instructed below.
0052 - Quicklook: run in terminal: `qlmanage -g <path to kritaquicklook.qlgenerator> -c image -d2 -p <path to a kra file>`
0053 - Spotlight: install `kritaspotlight.mdimporter` inside `~/Library/Spotlight` and
0054 clear caches, then run `mdimport -d2 -t <path to a kra file>`. Installed
0055 mdimporter will be first in the list when running `mdimport -L`.