PARASITE REGISTRY ================= This document describes parasites in PIKA. Table of contents ----------------- Parasite registry Table of contents Audience 1. Namespace 2. Known prefixes 3. Known global parasites 4. Known image parasites 5. Known layer/drawable parasites 6. Parasite format Audience -------- This document is designed for the convenience of PIKA developers. It does not need to concern users. >>>> If your plug-in or script writes parasites, please >>>> amend this file in the Git repository or submit patches to >>>> pika-developer-list@gnome.org 1. NAMESPACE ============ Plug-in-specific data should be prefixed by the plug-in function name and a slash, i.e. private data of plug_in_displace should be named like: plug_in_displace/data1 plug_in_displace/data2 etc. Global data follows no strict rules. 2. KNOWN PREFIXES ================= "tiff" : The standard PIKA TIFF plugin "jpeg" : The standard PIKA JPEG plugin "png" : The standard PIKA PNG plugin "dcm" : The standard PIKA DICOM plugin "pika" : For common and standard parasites 3. KNOWN GLOBAL PARASITES ========================= "jpeg-save-defaults" (GLOBAL, PERSISTENT) Default save parameters used by the JPEG plug-in. "png-save-defaults" (GLOBAL, PERSISTENT) Default save parameters used by the PNG plug-in. "/_fu_data" (GLOBAL, IMAGE, DRAWABLE, PERSISTENT) The Pika::Fu module (Perl) might store the arguments of the last plug-in invocation. It is usually attached to images, but might also be found globally. The data format is either pure character data (Data::Dumper) or a serialized data stream created by Storable::nfreeze. "exif-orientation-rotate" (GLOBAL, PERSISTENT) Whether a load plug-in should automatically rotate the image according to the orientation specified in the EXIF data. This has values "yes" or "no". If the parasite is not set, the plug-in should ask the user what to do. This parasite may be removed in a future version (assuming always yes). 4. KNOWN IMAGE PARASITES ======================== "pika-comment" (IMAGE, PERSISTENT) Standard GIF-style image comments. This parasite should be human-readable text in UTF-8 encoding. A trailing \0 might be included and is not part of the comment. Note that image comments may also be present in the "pika-metadata" parasite. "pika-brush-name" (IMAGE, PERSISTENT) A string in UTF-8 encoding specifying the name of a PIKA brush. Currently, the gbr plug-in uses this parasite when loading and saving .gbr files. A trailing \0 might be included and is not part of the name. "pika-brush-pipe-name" (IMAGE, PERSISTENT) A string in UTF-8 encoding specifying the name of a PIKA brush pipe. Currently, the gih plug-in uses this parasite when loading and saving .gih files. A trailing \0 might be included and is not part of the name. "pika-brush-pipe-parameters" (IMAGE, PERSISTENT) This is all very preliminary: A string, containing parameters describing how an brush pipe should be used. The contents is a space-separated list of keywords and values. The keyword and value are separated by a colon. This parasite is currently attached to an image by the psp plug-in when it loads a .tub file (Paint Shop Pro picture tube). It is used (first attached with values asked from the user, if nonexistent) by the gpb plug-in when it saves a .gih file. The .gih file contains the same text in it. The keywords are: ncells: the number of brushes in the brush pipe step: the default spacing for the pipe dim: the dimension of the pipe. The number of cells in the pipe should be equal to the product of the ranks of each dimension. cols: number of columns in each layer of the image, to be used when editing the pipe as a PIKA image rows: ditto for rows. Note that the number of columns and rows not necessarily are identical to the ranks of the dimensions of a pipe, but in the case of two- and three-dimensional pipes, it probably is. rank0, rank1, ...: (one for each dimension): the index range for that dimension placement: "default", "constant" or "random". "constant" means use the spacing in the first brush in the pipe. "random" means perturb that with some suitable random number function. (Hmm, would it be overdoing it if the pipe also could specify what random function and its parameters...?) sel0, sel1, ...: "default", "random", "incremental", "angular", "pressure", "velocity", and whatever else suitable we might think of ;-) Determines how one index from each dimension is selected (until we have pinpointed the brush to use). "pika-image-grid" (IMAGE, PERSISTENT) The PikaGrid object serialized to a string. Saved as parasite to keep the XCF files backwards compatible. Although pika-1.2 does not know how to handle the image grid, it keeps the grid information intact. "pika-pattern-name" (IMAGE, PERSISTENT) A string in UTF-8 encoding specifying the name of a PIKA pattern. Currently, the pat plug-in uses this parasite when loading and saving .pat files. A trailing \0 might be included and is not part of the name. "tiff-save-options" (IMAGE) The TiffSaveVals structure from the TIFF plugin. "jpeg-save-options" (IMAGE) The JpegSaveVals structure from the JPEG plugin. "jpeg-exif-data" (IMAGE) (deprecated) The ExifData structure serialized into a uchar* blob from libexif. This is deprecated in favor of "exif-data". "jpeg-original-settings" (IMAGE, PERSISTENT) The settings found in the original JPEG image: quality (IJG), color space, component subsampling and quantization tables. These can be reused when saving the image in order to minimize quantization losses and keep the same size/quality ratio. "gamma" (IMAGE, PERSISTENT) The original gamma this image was created/saved. For JPEG; this is always one, for PNG it's usually taken from the image data. PIKA might use and modify this. The format is an ascii string with the gamma exponent as a flotingpoint value. Example: for sRGB images this might contain "0.45454545" "chromaticity" (IMAGE, PERSISTENT) This parasite contains 8 floatingpoint values (ascii, separated by whitespace) specifying the x and y coordinates of the whitepoint, the red, green and blue primaries, in this order. Example: for sRGB images this might contain "0.3127 0.329 0.64 0.33 0.3 0.6 0.15 0.06" wx wy rx ry gx gy bx by "rendering-intent" (IMAGE, PERSISTENT) This specifies the rendering intent of the image. It's a value between 0 and 3, again in ascii: 0 - perceptual (e.g. for photographs) 1 - relative colorimetric (e.g. for logos) 2 - saturation-preserving (e.g. for business charts) 3 - absolute colorimetric "hot-spot" (IMAGE, PERSISTENT) Use this parasite to store an image's "hot spot". Currently used by the XBM plugin to store mouse cursor hot spots. Example: a hot spot at coordinates (5,5) is stored as "5 5" "exif-data" (IMAGE, PERSISTENT) The ExifData structure serialized into a character array by libexif (using exif_data_save_data). If a "pika-metadata" parasite is present, it should take precedence over this one. "pika-metadata" (IMAGE, PERSISTENT) The metadata associated with the image, serialized as one XMP packet. This metadata includes the contents of any XMP, EXIF and IPTC blocks from the original image, as well as user-specified values such as image comment, copyright, license, etc. "icc-profile" (IMAGE, PERSISTENT | UNDOABLE) This contains an ICC profile describing the color space the image was produced in. TIFF images stored in PhotoShop do oftentimes contain embedded profiles. An experimental color manager exists to use this parasite, and it will be used for interchange between TIFF and PNG (identical profiles) "icc-profile-name" (IMAGE, PERSISTENT | UNDOABLE) The profile name is a convenient name for referring to the profile. It is for example used in the PNG file format. The name must be stored in UTF-8 encoding. If a file format uses a different character encoding, it must be converted to UTF-8 for use as a parasite. "decompose-data" (IMAGE, NONPERSISTENT) Starting with PIKA 2.4, this is added to images produced by the decompose plug-in, and contains information necessary to recompose the original source RGB layer from the resulting grayscale layers. It is ascii; a typical example would be "source=2 type=RGBA 4 5 6 7". This means that layer 2 was decomposed in RGBA mode, giving rise to layers 4, 5, 6, and 7. "print-settings" (IMAGE, NONPERSISTENT) This parasite is stored by the Print plug-in and holds settings done in the Print dialog. It also has a version field so that changes to the parasite can be done. PIKA 2.4 used version 0.3. The format is GKeyFile. A lot of the contents are identical to what is stored in ~/.pika-2.x/print-settings but the parasite has some additional image-related fields. "print-page-setup" (IMAGE, NONPERSISTENT) This parasite is stored by the Print plug-in and holds settings done in the Page Setup dialog. The format is GKeyFile as created from GtkPageSetup. The content is identical to what is stored in ~/.pika-2.x/print-page-setup. "dcm/XXXX-XXXX-AA" (IMAGE, PERSISTENT) These parasites are stored by the Dicom plug-in and hold the DICOM element information for that image. The format is raw binary data as read from the original image. where: XXXX is a 4-digit ascii encoded hexadecimal number AA is a two character ascii value representing the Dicom element's Value Representation (VR) 5. KNOWN LAYER/DRAWABLE PARASITES ================================= "pika-text-layer" (LAYER, PERSISTENT) The associated PikaText object serialized to a string. For convenience the string is terminated by a trailing '\0'. The idea of using a parasite for text layers is to keep the XCF files backward compatible. Although pika-1.2 doesn't know how to handle the text layer, it keeps the parasite intact. "gfig" (LAYER, PERSISTENT) As of PIKA 2.2, the gfig plug-in creates its own layers, and stores a representation of the figure as a layer parasite. The parasite contains a GFig save file, in an ascii format. If gfig is started while the active layer contains a "gfig" parasite, the contents of the parasite are loaded at startup. 6. PARASITE FORMAT ================== The parasite data format is not rigidly specified. For non-persistent parasites you are entirely free, as the parasite data does not survive the current pika session. If you need persistent data, you basically have to choose between the following alternatives (also, having some standard for non-persistent data might be fine as well): - Cook your own binary data format You can invent your own data format. This means that you will either loose totally (consider endian-ness or version-ness issues) or you will get yourself into deep trouble to get it "right" in all cases. - Use character (string) data Obvious to Perl people but less so to C programmers: just sprintf your data into a string (e.g. "SIZE 100x200 XRES 300 YRES 300") and store that in the parasite, and later sscanf it again. This often solves most of the problems you might encounter, makes for easier debugging and more robustness (consider the case when you add more entries to your persistent data: older plug-ins might be able to read the relevant parts and your application can detect missing fields easily). The drawback is that your data is likely to be larger than a compact binary representation would be. Not much a problem for most applications, though. You could also use one parasite per field you store, i.e. foo-size, foo-offset-x, foo-offset-y etc... - Use the libpikaconfig serialize functions This is a special case of the previous one, using the convenience functions provided by libpikaconfig. If you are not concerned about the size of the string representation of your data, you can use pika_config_serialize_to_string() and other functions to easily convert your data to/from a character string.