parasites.txt 12.4 KB
Newer Older
1

2
PARASITE REGISTRY
3 4
=================

5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
This document describes parasites in GIMP. 


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
--------
29 30 31
This document is designed for the convenience of GIMP developers.
It does not need to concern users.

32 33 34
>>>> If your plug-in or script writes parasites, please
>>>> amend this file in the Git repository or submit patches to
>>>> gimp-developer-list@gnome.org
35 36


37 38
1. NAMESPACE
============
Marc Lehmann's avatar
Marc Lehmann committed
39 40 41 42 43 44 45 46 47 48

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.

49 50 51

2. KNOWN PREFIXES
=================
52

Marc Lehmann's avatar
Marc Lehmann committed
53 54
"tiff"    : The standard GIMP TIFF plugin
"jpeg"    : The standard GIMP JPEG plugin
55
"png"     : The standard GIMP PNG plugin
56
"dcm"     : The standard GIMP DICOM plugin
Marc Lehmann's avatar
Marc Lehmann committed
57
"gimp"    : For common and standard parasites
58

59 60 61

3. KNOWN GLOBAL PARASITES
=========================
62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82

"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.

"<plug-in>/_fu_data" (GLOBAL, IMAGE, DRAWABLE, PERSISTENT)
        The Gimp::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).

83 84 85

4. KNOWN IMAGE PARASITES
========================
86

Marc Lehmann's avatar
Marc Lehmann committed
87
"gimp-comment" (IMAGE, PERSISTENT)
Marc Lehmann's avatar
Marc Lehmann committed
88
        Standard GIF-style image comments.  This parasite should be
89
        human-readable text in UTF-8 encoding.  A trailing \0 might
90 91
        be included and is not part of the comment.  Note that image
        comments may also be present in the "gimp-metadata" parasite.
92

93 94 95 96 97 98
"gimp-brush-name" (IMAGE, PERSISTENT)
        A string in UTF-8 encoding specifying the name of a GIMP 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.

99 100 101 102 103 104
"gimp-brush-pipe-name" (IMAGE, PERSISTENT)
        A string in UTF-8 encoding specifying the name of a GIMP 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.

Michael Natterer's avatar
Michael Natterer committed
105
"gimp-brush-pipe-parameters" (IMAGE, PERSISTENT)
Tor Lillqvist's avatar
Tor Lillqvist committed
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121
	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
122
	dim: the dimension of the pipe. The number of cells
Tor Lillqvist's avatar
Tor Lillqvist committed
123 124 125 126 127 128 129 130
		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 GIMP 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.
131
	rank0, rank1, ...: (one for each dimension): the index range
Tor Lillqvist's avatar
Tor Lillqvist committed
132
		for that dimension
133 134 135 136 137 138
	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...?)
139 140
	sel0, sel1, ...: "default", "random", "incremental", "angular",
		"pressure", "velocity", and whatever else suitable we might
141
		think of ;-) Determines how one index from each dimension is
142
		selected (until we have pinpointed the brush to use).
Tor Lillqvist's avatar
Tor Lillqvist committed
143

144 145 146 147 148 149
"gimp-image-grid" (IMAGE, PERSISTENT)
        The GimpGrid object serialized to a string. Saved as parasite
        to keep the XCF files backwards compatible. Although gimp-1.2
        does not know how to handle the image grid, it keeps the grid
        information intact.

150 151 152 153 154 155
"gimp-pattern-name" (IMAGE, PERSISTENT)
        A string in UTF-8 encoding specifying the name of a GIMP 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.

Marc Lehmann's avatar
Marc Lehmann committed
156 157
"tiff-save-options" (IMAGE)
        The TiffSaveVals structure from the TIFF plugin.
Marc Lehmann's avatar
Marc Lehmann committed
158

Marc Lehmann's avatar
Marc Lehmann committed
159 160
"jpeg-save-options" (IMAGE)
        The JpegSaveVals structure from the JPEG plugin.
Marc Lehmann's avatar
Marc Lehmann committed
161

162
"jpeg-exif-data" (IMAGE) (deprecated)
163
        The ExifData structure serialized into a uchar* blob from
164
        libexif. This is deprecated in favor of "exif-data".
165

166 167 168 169 170 171
"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.

Marc Lehmann's avatar
Marc Lehmann committed
172 173
"gamma" (IMAGE, PERSISTENT)
	The original gamma this image was created/saved. For JPEG; this is
174
        always one, for PNG it's usually taken from the image data. GIMP
Marc Lehmann's avatar
Marc Lehmann committed
175 176 177 178 179 180
        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)
181
	This parasite contains 8 floatingpoint values (ascii, separated by
Marc Lehmann's avatar
Marc Lehmann committed
182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197
        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

Michael Natterer's avatar
Michael Natterer committed
198 199 200 201 202 203
"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"

204 205
"exif-data" (IMAGE, PERSISTENT)
        The ExifData structure serialized into a character array by
206 207
        libexif (using exif_data_save_data). If a "gimp-metadata"
        parasite is present, it should take precedence over this one.
208

209 210 211 212 213 214
"gimp-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.
215

216
"icc-profile" (IMAGE, PERSISTENT | UNDOABLE)
217 218 219 220 221
	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)
222

223
"icc-profile-name" (IMAGE, PERSISTENT | UNDOABLE)
224 225 226 227 228
        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.
229

230
"decompose-data" (IMAGE, NONPERSISTENT) 
231
        Starting with GIMP 2.4, this is added to images produced by
232 233 234 235 236 237
        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.

Sven Neumann's avatar
Sven Neumann committed
238
"print-settings" (IMAGE, NONPERSISTENT) 
239 240 241 242 243 244 245
        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. GIMP 2.4 used version 0.3.
        The format is GKeyFile. A lot of the contents are identical to
        what is stored in ~/.gimp-2.x/print-settings but the parasite
        has some additional image-related fields.

Sven Neumann's avatar
Sven Neumann committed
246
"print-page-setup" (IMAGE, NONPERSISTENT) 
247 248 249 250 251
        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
	~/.gimp-2.x/print-page-setup.

252
"dcm/XXXX-XXXX-AA" (IMAGE, PERSISTENT)
253 254 255 256 257
        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
258
                 element's Value Representation (VR)
259

260 261 262

5. KNOWN LAYER/DRAWABLE PARASITES
=================================
263 264 265 266 267 268 269 270

"gimp-text-layer" (LAYER, PERSISTENT)
        The associated GimpText 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 gimp-1.2 doesn't know how
        to handle the text layer, it keeps the parasite intact.

271 272 273 274 275 276 277
"gfig" (LAYER, PERSISTENT)
        As of GIMP 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.

278

279 280
6. PARASITE FORMAT
==================
Marc Lehmann's avatar
Marc Lehmann committed
281

282
The parasite data format is not rigidly specified. For non-persistent
Marc Lehmann's avatar
Marc Lehmann committed
283
parasites you are entirely free, as the parasite data does not survive the
284
current gimp session. If you need persistent data, you basically have to
Marc Lehmann's avatar
Marc Lehmann committed
285
choose between the following alternatives (also, having some standard for
286
non-persistent data might be fine as well):
Marc Lehmann's avatar
Marc Lehmann committed
287

288
- Cook your own binary data format
Marc Lehmann's avatar
Marc Lehmann committed
289 290 291 292 293
  
  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.

294
- Use character (string) data
Marc Lehmann's avatar
Marc Lehmann committed
295

296
  Obvious to Perl people but less so to C programmers: just sprintf your
Marc Lehmann's avatar
Marc Lehmann committed
297 298 299 300
  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
301
  persistent data: older plug-ins might be able to read the relevant
Marc Lehmann's avatar
Marc Lehmann committed
302 303 304 305 306
  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.

Marc Lehmann's avatar
Marc Lehmann committed
307 308 309
  You could also use one parasite per field you store, i.e. foo-size,
  foo-offset-x, foo-offset-y etc...

310 311 312 313 314 315 316
- Use the libgimpconfig serialize functions

  This is a special case of the previous one, using the convenience
  functions provided by libgimpconfig.  If you are not concerned about
  the size of the string representation of your data, you can use
  gimp_config_serialize_to_string() and other functions to easily
  convert your data to/from a character string.