root/trunk/bindings/python/README.html

Revision 976, 8.1 KB (checked in by Paul Kienzle, 3 years ago)

Python bindings to libNeXus. Refs #101
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<head>
3<title>
4Nexus Python API - README
5</title>
6</head>
7
8<body>
9<!-- start content -->
10
11<h1>Nexus Python API - README </h1>
12<hr>
13<table id="toc" class="toc" summary="Contents"><tbody><tr><td><h2>Contents</h2> </a>
14
15<ul>
16
17<li ><a href="#Overview">1. Overview</a>
18
19<li ><a href="#Installation">2. Installation</a>
20<ul>
21
22<li ><a href="#Requirements">2.1 Requirements</a></li>
23<li><a href="#Building and Installing">2.2 Building and Installing </a></li>
24<li><a href="#Linux">2.3 Linux </a></li>
25<li><a href="#Windows">2.4 Windows </a></li>
26
27</ul>
28
29<li ><a href="#Using API from Python">3. Using API from Python</a>
30<ul>
31
32<li><a href="#Test Files">3.1 Test Files </a></li>
33<li><a href="#Using The API And An Example">3.2 Using The API And An Example</a></li>
34<li><a href="#NeXus API Routines">3.3 NeXus API Routines</a></li>
35
36
37</ul>
38</ul>
39
40
41<a name="#Overview"></a><h2> Overview</h2>
42
43<p>NeXus Python Api binds the NeXus libraries to Python. It brings functionality of the NeXus API to Python for reading, writing and modifying NeXus Files. Python NeXus API imitates the functionality NeXus API though with a more object oriented flavour.
44
45<p>Information on NeXus Dataformat: <A HREF="http://www.nexusformat.org/Introduction">http://www.nexusformat.org/Introduction</A>.
46</p>
47<p>
48Information on IDL: <A HREF="http://www.ittvis.com/">http://www.nexusformat.org/Introduction</A>.
49</p>
50
51<p><br> </p>
52
53<a name="Installation"></a><h2> Installation</h2>
54
55<a name="Requirements"></a><h3> Requirements</h3>
56<p>
57This package provides a ctypes binding from Python+numpy to the precompiled NeXus library.
58
59It has been tested on Python 2.5 in Windows, OS X and Linux. 
60
61The bindings should be easily modified for any version of Python which supports
62ctypes and numpy.
63</p>
64
65<p>
66
67<p>  The NeXus packages and installation instructions are available at
68<A HREF="http://www.nexusformat.org/Download">http://www.nexusformat.org/Download</A>. </p>
69</p>
70
71<P>For Windows the NeXus Data Format
72Windows Installer Kit, which includes the necessary hdf5, hdf4 and
73xml libraries, is recommended.
74<A HREF="http://download.nexusformat.org/kits/windows/">http://download.nexusformat.org/kits/windows/ </A></P>
75
76</p>
77
78<a href="Building and Installing"></a><h3>Building and Installing</h3>
79
80This package uses the standard distutils installer for python.
81<TABLE WIDTH=85% BORDER=1 CELLPADDING=4 CELLSPACING=3 ALIGN=CENTER style="background-color: rgb(238, 238, 238);" >
82        <COL WIDTH=376>
83        <THEAD>
84                <TR>
85                <TD WIDTH=376 VALIGN=TOP>
86<pre>
87$ python setup.py install
88</pre>
89                </TD>
90                </TR>
91        </THEAD>
92</TABLE>
93
94You will also need to make sure that libNeXus can be found.  For windows, libNeXus.dll and
95the associated hdf/xml dlls should be together in nxs.py directory.  The package will also look in the
96standard nexus windows installer location, C:/Program Files/NeXus Data Format/.  For Linux, libNeXus.so
97should be in nxs.py directory, /usr/lib, /usr/local/lib, or one of the directories listed on LD_LIBRARY_PATH.
98For Apple OS X, libNeXus.dylib should be in the nxs.py directory, /usr/lib, /usr/local/lib, or one of the
99directories listed on DYLD_LIBRARY_PATH.  If the file is not in a standard place with the standard name,
100set NEXUSLIB to the full path to the NeXus library.
101
102<a name="Using API from Python"></a><h2> Using API from Python</h2>
103
104<a name="Test Files"></a><h3> Test Files</h3>
105
106<P>The Python NeXus-API includes nxstest.py, which provides similar
107tests to the original C api file napi_test.c.</P>
108
109</P>After installing, you can run the test using:
110<pre>
111    python [options] [formats]
112</pre>
113where options are -q for quiet and -x for external, and formats are
114hdf4, hdf5 and xml.  The default is to test hdf5 format read/write.
115</P>
116
117<a name="Using The API And An Example"></a><h3> Using The API And An Example</h3> 
118
119<p> The API's functions aim to reproduce
120the funtionality of the C API closely. Some low level functionality has been hidden from the user. Memory allocation
121functions NXmalloc and NXfree are done automatically in the API when needed.  The file handle
122is an object with methods rather than a parameter to functions.  Instead of checking status codes, errors raise
123exceptions.</p>
124
125<p>The input and returned values match the format of the data in the files.  On return, python creates
126values of the correct type.  However on input, numeric types must be created correctly using
127numpy.array(...,dtype='type'). The matching datatypes are:
128
129
130<TABLE BORDER=1 WIDTH=50% CELLPADDING=2 CELLSPACING=1 ALIGN=CENTER style="background-color: rgb(238, 238, 238);">
131        <COL WIDTH=373>
132        <THEAD>
133                <TR style="background-color: rgb(204, 204, 204);">
134                <TD WIDTH=373 VALIGN=TOP>
135                NeXus Datatype
136                </TD>
137                <TD WIDTH=373 VALIGN=TOP>
138                Python Datatype
139                </TD>
140
141                </TR>
142                <TR>
143                <TD WIDTH=373 VALIGN=TOP>
144                NX_CHAR
145                </TD>
146                <TD WIDTH=373 VALIGN=TOP>
147                'char'
148                </TD>
149                </TR>
150
151                <TR>
152                <TD WIDTH=373 VALIGN=TOP>
153                NX_FLOAT32
154                </TD>
155                <TD WIDTH=373 VALIGN=TOP>
156                'float32'
157                </TD>
158                </TR>
159
160
161                <TR>
162                <TD WIDTH=373 VALIGN=TOP>
163                NX_FLOAT64
164                </TD>
165                <TD WIDTH=373 VALIGN=TOP>
166                'float64'
167                </TD>
168                </TR>
169
170                <TR>
171                <TD WIDTH=373 VALIGN=TOP>
172                NX_UINT8
173                </TD>
174                <TD WIDTH=373 VALIGN=TOP>
175                'uint8'
176                </TD>
177                </TR>
178
179                <TR>
180                <TD WIDTH=373 VALIGN=TOP>
181                NX_INT16
182                </TD>
183                <TD WIDTH=373 VALIGN=TOP>
184                'int16'
185                </TD>
186                </TR>
187
188
189                <TR>
190                <TD WIDTH=373 VALIGN=TOP>
191                NX_UINT16
192                </TD>
193                <TD WIDTH=373 VALIGN=TOP>
194                'uint16'
195                </TD>
196                </TR>
197
198                <TR>
199                <TD WIDTH=373 VALIGN=TOP>
200                NX_INT32
201                </TD>
202                <TD WIDTH=373 VALIGN=TOP>
203                'int32'
204                </TD>
205                </TR>
206
207
208                <TR>
209                <TD WIDTH=373 VALIGN=TOP>
210                NX_UINT32
211                </TD>
212                <TD WIDTH=373 VALIGN=TOP>
213                'uint32'
214                </TD>
215                </TR>
216
217        </THEAD>
218</TABLE>
219
220<p> <br> </p>
221Here is simple example program that demonstrates the basic functions and most important differences between the C Nexus Api and the Python Nexus API.
222<ol>
223<li>Creates a NeXus file with access method HDF5</li>
224<li>adds datagroups</li>
225<li>makes a data array of data type NX_INT32</li>
226<li>puts data to the array</li>
227<li>reads the data and attributes</li>
228<li>prints data and attribute value</li>
229<li>closes the groups and the file.</li>
230</ol>
231
232
233
234<TABLE WIDTH=85% BORDER=1 CELLPADDING=4 CELLSPACING=3 ALIGN=CENTER style="background-color: rgb(238, 238, 238);" >
235        <COL WIDTH=376>
236        <THEAD>
237                <TR>
238                <TD WIDTH=376 VALIGN=TOP>
239<pre>
240import nxs,numpy
241
242# Access method accepts strings or integer (e.g., nxs.ACC_CREATE5)
243f = nxs.open("test.h5", 'w5')
244f.makegroup("testgroup", "NXentry")
245f.opengroup("testgroup", "NXentry")
246f.makegroup("anothergroup", "NXentry")
247
248# Some data to store in the file, this of type int16
249data = numpy.array([[0,1,2,3],[4,5,6,7],[8,9,10,11],[12,13,14,15] ],'int16')
250
251# Make a data set for the array. Note that this could also
252# be done as f.makedata('data1','int16',[4,4])
253f.makedata('data1', dtype=data.dtype, shape=data.shape)
254f.opendata("data1")
255f.putdata(data)
256
257# Attribute type can be inferred from the data or specified.  If inferred, it
258# must match the type of the data.  Attributes are scalars or strings, with
259# string length inferred from value.
260f.putattr('integer-attribute', 42, 'int16')
261f.putattr('double-attribute', 3.14159)
262f.closedata()
263# NeXus returns arrays from getattr/getdata/getslab
264f.opendata("data1")
265print 'data :',f.getdata()
266
267# getnext functions return tuples
268attrname,length,type = f.getnextattr ()
269value = f.getattr(attrname, length, type)
270print 'first attribute: ', value
271
272# ... or you can use iterators for attrs and entries
273print 'all attributes'
274for attr,value in f.attrs():
275    print "  %s: %s"%(attr,value)
276
277f.closedata()
278f.closegroup()
279f.close()
280</pre>
281                </TD>
282                </TR>
283        </THEAD>
284</TABLE>
285
286</p>
287
288<a name="NeXus API Routines"></a><h3> NeXus API Routines</h3>
289<p>Documentation for the individual methods, and how they differ
290from the basic NAPI methods is available from the Python command
291line.  Rather than duplicate it here, use the following in Python:
292
293<TABLE WIDTH=85% BORDER=1 CELLPADDING=4 CELLSPACING=3 ALIGN=CENTER style="background-color: rgb(238, 238, 238);" >
294        <COL WIDTH=376>
295        <THEAD>
296                <TR>
297                <TD WIDTH=376 VALIGN=TOP>
298<pre>
299import nxs
300help(nxs)
301</pre>
302                </TD>
303                </TR>
304        </THEAD>
305</TABLE>
306</p>
307</body></html>
Note: See TracBrowser for help on using the browser.