1
2
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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<title>libics: Usage</title>
<link rel="stylesheet" href="libics.css" type="text/css" title="default">
<!--[if lte IE 6]>
<link rel="stylesheet" href="iexplorefix.css" type="text/css" title="default">
<![endif]-->
</head>
<body>
<p class=header>libics v.1.7.0 Online Documentation. ©2000-2010 by Cris Luengo and others.</p>
<div class="navbar">
<ul>
<li><a href=".">libics home</a></li>
<li><a href="Documentation.html" class="selected">Documentation</a>
<ul>
<li><a href="Usage.html" class="selected">Usage of libics</a></li>
<li><a href="TopLevelFunctions.html">Top-level interface</a></li>
<li><a href="LowLevelFunctions.html">Low-level interface</a></li>
<li><a href="Ics_Header.html">Ics_Header</a></li>
<li><a href="Ics_DataRepresentation.html">Ics_DataRepresentation</a></li>
<li><a href="Ics_ImelRepresentation.html">Ics_ImelRepresentation</a></li>
<li><a href="Ics_Error.html">Ics_Error</a></li>
<li><a href="Enums.html">Other enums</a></li>
</ul>
</li>
<li><a href="Credits.html">Credits</a></li>
<li><a href="Links.html">Links</a></li>
<li><a href="https://github.com/svi-opensource/libics/releases">Download</a></li>
<li><a href="https://github.com/svi-opensource/libics">GitHub</a></li>
</ul>
</div>
<h1>Usage of libics</h1>
<p>The recommended way of using this library is through the
<a href="TopLevelFunctions.html">top-level interface</a>. It is also possible
to use some of the <a href="LowLevelFunctions.html">low-level functions</a>,
together with the
<tt class="typeident"><a href="Ics_Header.html">Ics_Header</a></tt>
structure, to create ICS files. This is however not recommended since both are
subject to change.</p>
<p>Below are two sample functions that use the basic functionality in this
library. The first one reads an ICS file, the second one writes one. These
examples use only the top-level interface</p>
<p>For both reading and writing, the
<tt class="typeident"><a href="Ics_Header.html">ICS</a></tt>
data structure serves as a kind of <tt class="typeident">FILE</tt>
structure. It contains all the information on the open file. All library
functions have it as their first parameter. In the low-level interface
functions, this structure is called <tt class="typeident">Ics_Header</tt>,
which is just an alias.</p>
<h2>Reading ICS</h2>
<p>This sample code shows how to use the top-level interface to read an
ICS file. First,
<tt class="funcident"><a href="TopLevelFunctions.html#IcsOpen">IcsOpen</a></tt>
is called to open the file. Then some functions can be used to gain knowledge
of the image stored in the file. This can be used to allocate memory for
the image data. Finally,
<tt class="funcident"><a href="TopLevelFunctions.html#IcsGetData">IcsGetData</a></tt>
is used to read in the data. Note that this library allows to
read only parts of the image data (see
<tt class="funcident"><a href="TopLevelFunctions.html#IcsGetROIData">IcsGetROIData</a></tt>).
To clean up,
<tt class="funcident"><a href="TopLevelFunctions.html#IcsClose">IcsClose</a></tt>
must be called, it releases some memory allocated by the call to
<tt class="funcident"><a href="TopLevelFunctions.html#IcsOpen">IcsOpen</a></tt>.</p>
<!-- Begin of sample code for reading ICS !-->
<pre>
<span class="preprocess">#include "libics.h"</span>
<span class="typeident"><a href="Ics_Header.html">ICS</a></span>* <span class="varident">ip</span>;
<span class="typeident"><a href="Enums.html#Ics_DataType">Ics_DataType</a></span> <span class="varident">dt</span>;
<span class="keyword">int</span> <span class="varident">ndims</span>;
<span class="keyword">size_t</span> <span class="varident">dims</span>[<span class="constant">ICS_MAXDIM</span>];
<span class="keyword">size_t</span> <span class="varident">bufsize</span>;
<span class="keyword">void</span>* <span class="varident">buf</span>;
<span class="typeident"><a href="Ics_Error.html">Ics_Error</a></span> <span class="varident">retval</span>;
<span class="varident">retval</span> = <span class="funcident"><a href="TopLevelFunctions.html#IcsOpen">IcsOpen</a></span> (&<span class="varident">ip</span>, <span class="constant">"file.ics"</span>, <span class="constant">"r"</span>);
<span class="keyword">if</span> (<span class="varident">retval</span> != <span class="constant">IcsErr_Ok</span>)
<span class="comment">/* Flag error condition */</span> ;
<span class="funcident"><a href="TopLevelFunctions.html#IcsGetLayout">IcsGetLayout</a></span> (<span class="varident">ip</span>, &<span class="varident">dt</span>, &<span class="varident">ndims</span>, <span class="varident">dims</span>);
<span class="varident">bufsize</span> = <span class="funcident"><a href="TopLevelFunctions.html#IcsGetDataSize">IcsGetDataSize</a></span> (<span class="varident">ip</span>);
<span class="varident">buf</span> = <span class="funcident">malloc</span> (<span class="varident">bufsize</span>);
<span class="keyword">if</span> (<span class="varident">buf</span> == <span class="constant">NULL</span>)
<span class="comment">/* Flag error condition*/</span> ;
<span class="varident">retval</span> = <span class="funcident"><a href="TopLevelFunctions.html#IcsGetData">IcsGetData</a></span> (<span class="varident">ip</span>, <span class="varident">buf</span>, <span class="varident">bufsize</span>);
<span class="keyword">if</span> (<span class="varident">retval</span> != <span class="constant">IcsErr_Ok</span>)
<span class="comment">/* Flag error condition */</span> ;
<span class="comment">/*
* There are some other functions available to get
* more info on the image in the .ics file.
*/</span>
<span class="varident">retval</span> = <span class="funcident"><a href="TopLevelFunctions.html#IcsClose">IcsClose</a></span> (<span class="varident">ip</span>);
<span class="keyword">if</span> (<span class="varident">retval</span> != <span class="constant">IcsErr_Ok</span>)
<span class="comment">/* Flag error condition*/</span> ;
</pre>
<!-- End of sample code for reading ICS !-->
<h2>Writing ICS</h2>
<p>This sample code shows how to use the top-level interface to write an
ICS file. First,
<tt class="funcident"><a href="TopLevelFunctions.html#IcsOpen">IcsOpen</a></tt>
is called to open the file. What this does is allocate the
<tt class="typeident"><a href="Ics_Header.html">ICS</a></tt>
structure. Then a series of functions can be used to specify information
on the image to be written. Finally,
<tt class="funcident"><a href="TopLevelFunctions.html#IcsClose">IcsClose</a></tt>
is called to write the data to a file. This call also cleans up allocated
memory.</p>
<!-- Begin of sample code for writing ICS !-->
<pre>
<span class="preprocess">#include "libics.h"</span>
<span class="typeident"><a href="Ics_Header.html">ICS</a></span>* <span class="varident">ip</span>;
<span class="typeident"><a href="Enums.html#Ics_DataType">Ics_DataType</a></span> <span class="varident">dt</span> = <span class="constant">Ics_uint8</span>;
<span class="keyword">int</span> <span class="varident">ndims</span> = <span class="constant">3</span>;
<span class="keyword">size_t</span> <span class="varident">dims</span>[<span class="constant">3</span>] = {<span class="constant">256</span>, <span class="constant">256</span>, <span class="constant">256</span>};
<span class="keyword">size_t</span> <span class="varident">bufsize</span> = <span class="constant">256</span>*<span class="constant">256</span>*<span class="constant">256</span>;
<span class="keyword">void</span>* <span class="varident">buf</span> = <span class="varident">image_data</span>;
<span class="typeident"><a href="Ics_Error.html">Ics_Error</a></span> <span class="varident">retval</span>;
<span class="varident">retval</span> = <span class="funcident"><a href="TopLevelFunctions.html#IcsOpen">IcsOpen</a></span> (&<span class="varident">ip</span>, <span class="constant">"file.ics"</span>, <span class="constant">"w2"</span>);
<span class="keyword">if</span> (<span class="varident">retval</span> != <span class="constant">IcsErr_Ok</span>)
<span class="comment">/* Flag error condition */</span> ;
<span class="funcident"><a href="TopLevelFunctions.html#IcsSetLayout">IcsSetLayout</a></span> (<span class="varident">ip</span>, <span class="varident">dt</span>, <span class="varident">ndims</span>, <span class="varident">dims</span>);
<span class="funcident"><a href="TopLevelFunctions.html#IcsSetData">IcsSetData</a></span> (<span class="varident">ip</span>, <span class="varident">buf</span>, <span class="varident">bufsize</span>);
<span class="funcident"><a href="TopLevelFunctions.html#IcsSetCompression">IcsSetCompression</a></span> (<span class="varident">ip</span>, <span class="constant">IcsCompr_gzip</span>, <span class="constant">6</span>);
<span class="funcident"><a href="TopLevelFunctions.html#IcsAddHistoryString">IcsAddHistoryString</a></span> (<span class="varident">ip</span>, <span class="constant">"author"</span>, <span class="constant">"M.Y. Name"</span>);
<span class="comment">/*
* There are some other functions available to set
* image parameters in the .ics file.
*/</span>
<span class="varident">retval</span> = <span class="funcident"><a href="TopLevelFunctions.html#IcsClose">IcsClose</a></span> (<span class="varident">ip</span>);
<span class="keyword">if</span> (<span class="varident">retval</span> != <span class="constant">IcsErr_Ok</span>)
<span class="comment">/* Flag error condition */</span> ;
</pre>
<!-- End of sample code for writing ICS !-->
</body>
</html>
|
