Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / ImageMagick / de27d7631fa4cbb36c8bde6001d2c522774b3712 / . / www / api / property.html
blob: 56cedc229a7761c925ce05fdf7c22b9636f53bfc [file] [log] [blame]
Cristy594d2772015-11-15 10:47:42 -0500[diff] [blame]1
2
3
4
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5<!DOCTYPE html>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]6<html lang="en">
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]7<head>
Cristy594d2772015-11-15 10:47:42 -0500[diff] [blame]8 <meta name="google-site-verification" content="_bMOCDpkx9ZAzBwb2kF3PRHbfUUdFj2uO8Jd1AXArz4" />
cristy29f2c972015-07-28 13:37:46 +0000[diff] [blame]9 <title>ImageMagick: MagickCore, C API for ImageMagick: Get/Set Image Properties</title>
Cristy594d2772015-11-15 10:47:42 -0500[diff] [blame]10 <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
11 <meta name="application-name" content="ImageMagick"/>
12 <meta name="description" content="ImageMagick® is a software suite to create, edit, compose, or convert bitmap images. It can read and write images in a variety of formats (over 200) including PNG, JPEG, JPEG-2000, GIF, WebP, Postscript, PDF, and SVG. Use ImageMagick to resize, flip, mirror, rotate, distort, shear and transform images, adjust image colors, apply various special effects, or draw text, lines, polygons, ellipses and Bézier curves."/>
13 <meta name="application-url" content="http://www.imagemagick.org"/>
14 <meta name="generator" content="PHP"/>
15 <meta name="keywords" content="magickcore, c, api, for, imagemagick:, get/set, image, properties, ImageMagick, PerlMagick, image processing, image, photo, software, Magick++, OpenMP, convert"/>
16 <meta name="rating" content="GENERAL"/>
17 <meta name="robots" content="INDEX, FOLLOW"/>
18 <meta name="generator" content="ImageMagick Studio LLC"/>
19 <meta name="author" content="ImageMagick Studio LLC"/>
20 <meta name="revisit-after" content="2 DAYS"/>
21 <meta name="resource-type" content="document"/>
Cristyce4a3552015-12-14 13:53:35 -0500[diff] [blame]22 <meta name="copyright" content="Copyright (c) 1999-2015 ImageMagick Studio LLC"/>
Cristy594d2772015-11-15 10:47:42 -0500[diff] [blame]23 <meta name="distribution" content="Global"/>
24 <meta name="magick-serial" content="P131-S030410-R485315270133-P82224-A6668-G1245-1"/>
25 <link rel="icon" href="../images/wand.png"/>
26 <link rel="shortcut icon" href="../images/wand.ico"/>
27 <link rel="stylesheet" href="../css/magick.html"/>
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]28</head>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]29<body>
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]30<div class="main">
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]31<div class="magick-masthead">
32 <div class="container">
Cristye93be682015-11-26 09:07:51 -0500[diff] [blame]33 <script async="async" src="http://localhost/pagead/js/adsbygoogle.js"></script> <ins class="adsbygoogle"
Cristy594d2772015-11-15 10:47:42 -0500[diff] [blame]34 style="display:block"
35 data-ad-client="ca-pub-3129977114552745"
36 data-ad-slot="6345125851"
37 data-ad-format="auto"></ins>
cristy29f2c972015-07-28 13:37:46 +0000[diff] [blame]38 <script>
Cristy542697a2015-10-12 20:10:32 -0400[diff] [blame]39 (adsbygoogle = window.adsbygoogle || []).push({});
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]40 </script>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]41 <nav class="magick-nav">
cristy2f563d42015-05-06 23:36:51 +0000[diff] [blame]42 <a class="magick-nav-item " href="../index.html">Home</a>
cristyea2793e2015-05-31 16:52:26 +0000[diff] [blame]43 <a class="magick-nav-item " href="../binary-releases.html">Download</a>
cristy38185362015-05-07 20:09:56 +0000[diff] [blame]44 <a class="magick-nav-item " href="../command-line-tools.html">Tools</a>
Cristye93be682015-11-26 09:07:51 -0500[diff] [blame]45 <a class="magick-nav-item " href="../command-line-processing.html">Command-line</a>
cristyea2793e2015-05-31 16:52:26 +0000[diff] [blame]46 <a class="magick-nav-item " href="../resources.html">Resources</a>
47 <a class="magick-nav-item " href="api.html">Develop</a>
cristy5b8fe762015-06-09 16:24:03 +0000[diff] [blame]48 <a class="magick-nav-item " href="http://nextgen.imagemagick.org/script/search.php">Search</a>
cristya1890f02015-05-15 23:32:44 +0000[diff] [blame]49 <a class="magick-nav-item pull-right" href="http://www.imagemagick.org/discourse-server/">Community</a>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]50 </nav>
51 </div>
52</div>
53<div class="container">
cristy4e638cd2015-05-07 16:47:40 +0000[diff] [blame]54<div class="magick-header">
Cristy594d2772015-11-15 10:47:42 -0500[diff] [blame]55<p class="text-center"><a href="property.html#CloneImageProperties">CloneImageProperties</a> &#8226; <a href="property.html#DefineImageProperty">DefineImageProperty</a> &#8226; <a href="property.html#DeleteImageProperty">DeleteImageProperty</a> &#8226; <a href="property.html#DestroyImageProperties">DestroyImageProperties</a> &#8226; <a href="property.html#FormatImageProperty">FormatImageProperty</a> &#8226; <a href="property.html#GetImageProperty">GetImageProperty</a> &#8226; <a href="property.html#GetNextImageProperty">GetNextImageProperty</a> &#8226; <a href="property.html#InterpretImageProperties">InterpretImageProperties</a> &#8226; <a href="property.html#(void) LogMagickEvent(TraceEvent,GetMagickModule">(void) LogMagickEvent(TraceEvent,GetMagickModule</a> &#8226; <a href="property.html#RemoveImageProperty">RemoveImageProperty</a> &#8226; <a href="property.html#ResetImagePropertyIterator">ResetImagePropertyIterator</a> &#8226; <a href="property.html#SetImageProperty">SetImageProperty</a></p>
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]56
Cristye93be682015-11-26 09:07:51 -0500[diff] [blame]57<h2><a href="http://www.imagemagick.org/api/MagickCore/property_8c.html" id="CloneImageProperties">CloneImageProperties</a></h2>
cristycecc9492015-06-09 16:53:50 +0000[diff] [blame]58
59<p>CloneImageProperties() clones all the image properties to another image.</p>
60
61<p>The format of the CloneImageProperties method is:</p>
62
63<pre class="text">
64MagickBooleanType CloneImageProperties(Image *image,
65 const Image *clone_image)
66</pre>
67
68<p>A description of each parameter follows:</p>
69
70<dd>
71</dd>
72
73<dd> </dd>
74<dl class="dl-horizontal">
75<dt>image</dt>
76<dd>the image. </dd>
77
78<dd> </dd>
79<dt>clone_image</dt>
80<dd>the clone image. </dd>
81
82<dd> </dd>
83</dl>
Cristye93be682015-11-26 09:07:51 -0500[diff] [blame]84<h2><a href="http://www.imagemagick.org/api/MagickCore/property_8c.html" id="DefineImageProperty">DefineImageProperty</a></h2>
cristycecc9492015-06-09 16:53:50 +0000[diff] [blame]85
86<p>DefineImageProperty() associates an assignment string of the form "key=value" with an artifact or options. It is equivelent to SetImageProperty()</p>
87
88<p>The format of the DefineImageProperty method is:</p>
89
90<pre class="text">
91MagickBooleanType DefineImageProperty(Image *image,const char *property,
92 ExceptionInfo *exception)
93</pre>
94
95<p>A description of each parameter follows:</p>
96
97<dd>
98</dd>
99
100<dd> </dd>
101<dl class="dl-horizontal">
102<dt>image</dt>
103<dd>the image. </dd>
104
105<dd> </dd>
106<dt>property</dt>
107<dd>the image property. </dd>
108
109<dd> </dd>
110<dt>exception</dt>
111<dd>return any errors or warnings in this structure. </dd>
112
113<dd> </dd>
114</dl>
Cristye93be682015-11-26 09:07:51 -0500[diff] [blame]115<h2><a href="http://www.imagemagick.org/api/MagickCore/property_8c.html" id="DeleteImageProperty">DeleteImageProperty</a></h2>
cristycecc9492015-06-09 16:53:50 +0000[diff] [blame]116
117<p>DeleteImageProperty() deletes an image property.</p>
118
119<p>The format of the DeleteImageProperty method is:</p>
120
121<pre class="text">
122MagickBooleanType DeleteImageProperty(Image *image,const char *property)
123</pre>
124
125<p>A description of each parameter follows:</p>
126
127<dd>
128</dd>
129
130<dd> </dd>
131<dl class="dl-horizontal">
132<dt>image</dt>
133<dd>the image. </dd>
134
135<dd> </dd>
136<dt>property</dt>
137<dd>the image property. </dd>
138
139<dd> </dd>
140</dl>
Cristye93be682015-11-26 09:07:51 -0500[diff] [blame]141<h2><a href="http://www.imagemagick.org/api/MagickCore/property_8c.html" id="DestroyImageProperties">DestroyImageProperties</a></h2>
cristycecc9492015-06-09 16:53:50 +0000[diff] [blame]142
143<p>DestroyImageProperties() destroys all properties and associated memory attached to the given image.</p>
144
145<p>The format of the DestroyDefines method is:</p>
146
147<pre class="text">
148void DestroyImageProperties(Image *image)
149</pre>
150
151<p>A description of each parameter follows:</p>
152
153<dd>
154</dd>
155
156<dd> </dd>
157<dl class="dl-horizontal">
158<dt>image</dt>
159<dd>the image. </dd>
160
161<dd> </dd>
162</dl>
Cristye93be682015-11-26 09:07:51 -0500[diff] [blame]163<h2><a href="http://www.imagemagick.org/api/MagickCore/property_8c.html" id="FormatImageProperty">FormatImageProperty</a></h2>
cristycecc9492015-06-09 16:53:50 +0000[diff] [blame]164
165<p>FormatImageProperty() permits formatted property/value pairs to be saved as an image property.</p>
166
167<p>The format of the FormatImageProperty method is:</p>
168
169<pre class="text">
170MagickBooleanType FormatImageProperty(Image *image,const char *property,
171 const char *format,...)
172</pre>
173
174<p>A description of each parameter follows.</p>
175
176<dt> image</dt>
177<p>The image.</p>
178
179<dt> property</dt>
180<p>The attribute property.</p>
181
182<dt> format</dt>
183<p>A string describing the format to use to write the remaining arguments.</p>
184
Cristye93be682015-11-26 09:07:51 -0500[diff] [blame]185<h2><a href="http://www.imagemagick.org/api/MagickCore/property_8c.html" id="GetImageProperty">GetImageProperty</a></h2>
cristycecc9492015-06-09 16:53:50 +0000[diff] [blame]186
187<p>GetImageProperty() gets a value associated with an image property.</p>
188
189<p>This includes, profile prefixes, such as "exif:", "iptc:" and "8bim:" It does not handle non-prifile prefixes, such as "fx:", "option:", or "artifact:".</p>
190
191<p>The returned string is stored as a properity of the same name for faster lookup later. It should NOT be freed by the caller.</p>
192
193<p>The format of the GetImageProperty method is:</p>
194
195<pre class="text">
196const char *GetImageProperty(const Image *image,const char *key,
197 ExceptionInfo *exception)
198</pre>
199
200<p>A description of each parameter follows:</p>
201
202<dd>
203</dd>
204
205<dd> </dd>
206<dl class="dl-horizontal">
207<dt>image</dt>
208<dd>the image. </dd>
209
210<dd> </dd>
211<dt>key</dt>
212<dd>the key. </dd>
213
214<dd> </dd>
215<dt>exception</dt>
216<dd>return any errors or warnings in this structure. </dd>
217
218<dd> </dd>
219</dl>
Cristye93be682015-11-26 09:07:51 -0500[diff] [blame]220<h2><a href="http://www.imagemagick.org/api/MagickCore/property_8c.html" id="GetNextImageProperty">GetNextImageProperty</a></h2>
cristycecc9492015-06-09 16:53:50 +0000[diff] [blame]221
222<p>GetNextImageProperty() gets the next free-form string property name.</p>
223
224<p>The format of the GetNextImageProperty method is:</p>
225
226<pre class="text">
227char *GetNextImageProperty(const Image *image)
228</pre>
229
230<p>A description of each parameter follows:</p>
231
232<dd>
233</dd>
234
235<dd> </dd>
236<dl class="dl-horizontal">
237<dt>image</dt>
238<dd>the image. </dd>
239
240<dd> </dd>
241</dl>
Cristye93be682015-11-26 09:07:51 -0500[diff] [blame]242<h2><a href="http://www.imagemagick.org/api/MagickCore/property_8c.html" id="InterpretImageProperties">InterpretImageProperties</a></h2>
cristycecc9492015-06-09 16:53:50 +0000[diff] [blame]243
244<p>InterpretImageProperties() replaces any embedded formatting characters with the appropriate image property and returns the interpreted text.</p>
245
246<p>This searches for and replaces \n \r \ replaced by newline, return, and percent resp. &amp;lt; &amp;gt; &amp;amp; replaced by '&lt;', '&gt;', '&amp;' resp. replaced by percent</p>
247
248<p>x [x] where 'x' is a single letter properity, case sensitive). [type:name] where 'type' a is special and known prefix. [name] where 'name' is a specifically known attribute, calculated value, or a per-image property string name, or a per-image 'artifact' (as generated from a global option). It may contain ':' as long as the prefix is not special.</p>
249
250<p>Single letter substitutions will only happen if the character before the percent is NOT a number. But braced substitutions will always be performed. This prevents the typical usage of percent in a interpreted geometry argument from being substituted when the percent is a geometry flag.</p>
251
252<p>If 'glob-expresions' ('*' or '?' characters) is used for 'name' it may be used as a search pattern to print multiple lines of "name=value\n" pairs of the associacted set of properties.</p>
253
254<p>The returned string must be freed using DestoryString() by the caller.</p>
255
256<p>The format of the InterpretImageProperties method is:</p>
257
258<pre class="text">
259char *InterpretImageProperties(ImageInfo *image_info,
260 Image *image,const char *embed_text,ExceptionInfo *exception)
261</pre>
262
263<p>A description of each parameter follows:</p>
264
265<dd>
266</dd>
267
268<dd> </dd>
269<dl class="dl-horizontal">
270<dt>image_info</dt>
271<dd>the image info. (required) </dd>
272
273<dd> </dd>
274<dt>image</dt>
275<dd>the image. (optional) </dd>
276
277<dd> </dd>
278<dt>embed_text</dt>
279<dd>the address of a character string containing the embedded formatting characters. </dd>
280
281<dd> </dd>
282<dt>exception</dt>
283<dd>return any errors or warnings in this structure. </dd>
284
285<dd> </dd>
286</dl>
Cristye93be682015-11-26 09:07:51 -0500[diff] [blame]287<h2><a href="http://www.imagemagick.org/api/MagickCore/property_8c.html" id="(void)_LogMagickEvent(TraceEvent,GetMagickModule">(void) LogMagickEvent(TraceEvent,GetMagickModule</a></h2>
cristycecc9492015-06-09 16:53:50 +0000[diff] [blame]288
289<p>(void) LogMagickEvent(TraceEvent,GetMagickModule(),"s",image-&gt;filename); else if( image_info != (ImageInfo *) NULL &amp;&amp; IfMagickTrue(image_info-&gt;debug)) (void) LogMagickEvent(TraceEvent,GetMagickModule(),"s","no-image");</p>
290
Cristy882d9f42015-10-29 16:48:39 -0400[diff] [blame]291<p>if (embed_text == (const char *) NULL) return(ConstantString("")); p=embed_text;</p>
cristycecc9492015-06-09 16:53:50 +0000[diff] [blame]292
293<p>if (*p == '\0') return(ConstantString(""));</p>
294
Cristy882d9f42015-10-29 16:48:39 -0400[diff] [blame]295<p>if ((*p == '@') &amp;&amp; (IsPathAccessible(p+1) != MagickFalse)) { /* handle a '@' replace string from file */ interpret_text=FileToString(p+1,~0UL,exception); if (interpret_text != (char *) NULL) return(interpret_text); }</p>
cristycecc9492015-06-09 16:53:50 +0000[diff] [blame]296
297<p>/* Translate any embedded format characters. </p>
Cristye93be682015-11-26 09:07:51 -0500[diff] [blame]298<h2><a href="http://www.imagemagick.org/api/MagickCore/property_8c.html" id="RemoveImageProperty">RemoveImageProperty</a></h2>
cristycecc9492015-06-09 16:53:50 +0000[diff] [blame]299
300<p>RemoveImageProperty() removes a property from the image and returns its value.</p>
301
302<p>In this case the ConstantString() value returned should be freed by the caller when finished.</p>
303
304<p>The format of the RemoveImageProperty method is:</p>
305
306<pre class="text">
307char *RemoveImageProperty(Image *image,const char *property)
308</pre>
309
310<p>A description of each parameter follows:</p>
311
312<dd>
313</dd>
314
315<dd> </dd>
316<dl class="dl-horizontal">
317<dt>image</dt>
318<dd>the image. </dd>
319
320<dd> </dd>
321<dt>property</dt>
322<dd>the image property. </dd>
323
324<dd> </dd>
325</dl>
Cristye93be682015-11-26 09:07:51 -0500[diff] [blame]326<h2><a href="http://www.imagemagick.org/api/MagickCore/property_8c.html" id="ResetImagePropertyIterator">ResetImagePropertyIterator</a></h2>
cristycecc9492015-06-09 16:53:50 +0000[diff] [blame]327
328<p>ResetImagePropertyIterator() resets the image properties iterator. Use it in conjunction with GetNextImageProperty() to iterate over all the values associated with an image property.</p>
329
330<p>The format of the ResetImagePropertyIterator method is:</p>
331
332<pre class="text">
333ResetImagePropertyIterator(Image *image)
334</pre>
335
336<p>A description of each parameter follows:</p>
337
338<dd>
339</dd>
340
341<dd> </dd>
342<dl class="dl-horizontal">
343<dt>image</dt>
344<dd>the image. </dd>
345
346<dd> </dd>
347</dl>
Cristye93be682015-11-26 09:07:51 -0500[diff] [blame]348<h2><a href="http://www.imagemagick.org/api/MagickCore/property_8c.html" id="SetImageProperty">SetImageProperty</a></h2>
cristycecc9492015-06-09 16:53:50 +0000[diff] [blame]349
350<p>SetImageProperty() saves the given string value either to specific known attribute or to a freeform property string.</p>
351
352<p>Attempting to set a property that is normally calculated will produce an exception.</p>
353
354<p>The format of the SetImageProperty method is:</p>
355
356<pre class="text">
357MagickBooleanType SetImageProperty(Image *image,const char *property,
358 const char *value,ExceptionInfo *exception)
359</pre>
360
361<p>A description of each parameter follows:</p>
362
363<dd>
364</dd>
365
366<dd> </dd>
367<dl class="dl-horizontal">
368<dt>image</dt>
369<dd>the image. </dd>
370
371<dd> </dd>
372<dt>property</dt>
373<dd>the image property. </dd>
374
375<dd> </dd>
376<dt>values</dt>
377<dd>the image property values. </dd>
378
379<dd> </dd>
380<dt>exception</dt>
381<dd>return any errors or warnings in this structure. </dd>
382
383<dd> </dd>
384</dl>
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]385</div>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]386 <footer class="magick-footer">
cristy29f2c972015-07-28 13:37:46 +0000[diff] [blame]387 <p><a href="../support.html">Donate</a> •
388 <a href="../sitemap.html">Sitemap</a> •
cristy38185362015-05-07 20:09:56 +0000[diff] [blame]389 <a href="../links.html">Related</a> •
cristy29f2c972015-07-28 13:37:46 +0000[diff] [blame]390 <a href="../architecture.html">Architecture</a>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]391</p>
392 <p><a href="property.html#">Back to top</a> •
cristyea2793e2015-05-31 16:52:26 +0000[diff] [blame]393 <a href="http://pgp.mit.edu:11371/pks/lookup?op=get&amp;search=0x89AB63D48277377A">Public Key</a> •
cristy5b8fe762015-06-09 16:24:03 +0000[diff] [blame]394 <a href="http://nextgen.imagemagick.org/script/contact.php">Contact Us</a></p>
Cristyce4a3552015-12-14 13:53:35 -0500[diff] [blame]395 <p><small>© 1999-2015 ImageMagick Studio LLC</small></p>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]396 </footer>
397</div><!-- /.container -->
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]398
Cristye93be682015-11-26 09:07:51 -0500[diff] [blame]399 <script src="https://localhost/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
cristy29f2c972015-07-28 13:37:46 +0000[diff] [blame]400 <script src="http://nextgen.imagemagick.org/js/magick.html"></script>
cristy44cbd482013-08-04 20:53:36 +0000[diff] [blame]401</div>
cristy06f63f22012-10-31 00:50:07 +0000[diff] [blame]402</body>
cristy5a367e42015-05-05 12:39:18 +0000[diff] [blame]403</html>