/usr/share/nexus/doc/python/README.html is in python-nxs 4.3.2-svn1919-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<head>
<title>
Nexus Python API - README
</title>
</head>
<body>
<!-- start content -->
<h1>Nexus Python API - README </h1>
<hr>
<table id="toc" class="toc" summary="Contents"><tbody><tr><td><h2>Contents</h2> </a>
<ul>
<li ><a href="#Overview">1. Overview</a>
<li ><a href="#Installation">2. Installation</a>
<ul>
<li ><a href="#Requirements">2.1 Requirements</a></li>
<li><a href="#Building and Installing">2.2 Building and Installing </a></li>
<li><a href="#Linux">2.3 Linux </a></li>
<li><a href="#Windows">2.4 Windows </a></li>
</ul>
<li ><a href="#Using API from Python">3. Using API from Python</a>
<ul>
<li><a href="#Test Files">3.1 Test Files </a></li>
<li><a href="#Using The API And An Example">3.2 Using The API And An Example</a></li>
<li><a href="#NeXus API Routines">3.3 NeXus API Routines</a></li>
</ul>
</ul>
<a name="#Overview"></a><h2> Overview</h2>
<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.
<p>Information on NeXus Dataformat: <A HREF="http://www.nexusformat.org/Introduction">http://www.nexusformat.org/Introduction</A>.
</p>
<p>
Information on IDL: <A HREF="http://www.ittvis.com/">http://www.nexusformat.org/Introduction</A>.
</p>
<p><br> </p>
<a name="Installation"></a><h2> Installation</h2>
<a name="Requirements"></a><h3> Requirements</h3>
<p>
This package provides a ctypes binding from Python+numpy to the precompiled NeXus library.
It has been tested on Python 2.5 in Windows, OS X and Linux.
The bindings should be easily modified for any version of Python which supports
ctypes and numpy.
</p>
<p>
<p> The NeXus packages and installation instructions are available at
<A HREF="http://www.nexusformat.org/Download">http://www.nexusformat.org/Download</A>. </p>
</p>
<P>For Windows the NeXus Data Format
Windows Installer Kit, which includes the necessary hdf5, hdf4 and
xml libraries, is recommended.
<A HREF="http://download.nexusformat.org/kits/windows/">http://download.nexusformat.org/kits/windows/ </A></P>
</p>
<a href="Building and Installing"></a><h3>Building and Installing</h3>
This package uses the standard distutils installer for python.
<TABLE WIDTH=85% BORDER=1 CELLPADDING=4 CELLSPACING=3 ALIGN=CENTER style="background-color: rgb(238, 238, 238);" >
<COL WIDTH=376>
<THEAD>
<TR>
<TD WIDTH=376 VALIGN=TOP>
<pre>
$ python setup.py install
</pre>
</TD>
</TR>
</THEAD>
</TABLE>
You will also need to make sure that libNeXus can be found. For windows, libNeXus.dll and
the associated hdf/xml dlls should be together in nxs.py directory. The package will also look in the
standard nexus windows installer location, C:/Program Files/NeXus Data Format/. For Linux, libNeXus.so
should be in nxs.py directory, /usr/lib, /usr/local/lib, or one of the directories listed on LD_LIBRARY_PATH.
For Apple OS X, libNeXus.dylib should be in the nxs.py directory, /usr/lib, /usr/local/lib, or one of the
directories listed on DYLD_LIBRARY_PATH. If the file is not in a standard place with the standard name,
set NEXUSLIB to the full path to the NeXus library.
<a name="Using API from Python"></a><h2> Using API from Python</h2>
<a name="Test Files"></a><h3> Test Files</h3>
<P>The Python NeXus-API includes nxstest.py, which provides similar
tests to the original C api file napi_test.c.</P>
</P>After installing, you can run the test using:
<pre>
python [options] [formats]
</pre>
where options are -q for quiet and -x for external, and formats are
hdf4, hdf5 and xml. The default is to test hdf5 format read/write.
</P>
<a name="Using The API And An Example"></a><h3> Using The API And An Example</h3>
<p> The API's functions aim to reproduce
the funtionality of the C API closely. Some low level functionality has been hidden from the user. Memory allocation
functions NXmalloc and NXfree are done automatically in the API when needed. The file handle
is an object with methods rather than a parameter to functions. Instead of checking status codes, errors raise
exceptions.</p>
<p>The input and returned values match the format of the data in the files. On return, python creates
values of the correct type. However on input, numeric types must be created correctly using
numpy.array(...,dtype='type'). The matching datatypes are:
<TABLE BORDER=1 WIDTH=50% CELLPADDING=2 CELLSPACING=1 ALIGN=CENTER style="background-color: rgb(238, 238, 238);">
<COL WIDTH=373>
<THEAD>
<TR style="background-color: rgb(204, 204, 204);">
<TD WIDTH=373 VALIGN=TOP>
NeXus Datatype
</TD>
<TD WIDTH=373 VALIGN=TOP>
Python Datatype
</TD>
</TR>
<TR>
<TD WIDTH=373 VALIGN=TOP>
NX_CHAR
</TD>
<TD WIDTH=373 VALIGN=TOP>
'char'
</TD>
</TR>
<TR>
<TD WIDTH=373 VALIGN=TOP>
NX_FLOAT32
</TD>
<TD WIDTH=373 VALIGN=TOP>
'float32'
</TD>
</TR>
<TR>
<TD WIDTH=373 VALIGN=TOP>
NX_FLOAT64
</TD>
<TD WIDTH=373 VALIGN=TOP>
'float64'
</TD>
</TR>
<TR>
<TD WIDTH=373 VALIGN=TOP>
NX_UINT8
</TD>
<TD WIDTH=373 VALIGN=TOP>
'uint8'
</TD>
</TR>
<TR>
<TD WIDTH=373 VALIGN=TOP>
NX_INT16
</TD>
<TD WIDTH=373 VALIGN=TOP>
'int16'
</TD>
</TR>
<TR>
<TD WIDTH=373 VALIGN=TOP>
NX_UINT16
</TD>
<TD WIDTH=373 VALIGN=TOP>
'uint16'
</TD>
</TR>
<TR>
<TD WIDTH=373 VALIGN=TOP>
NX_INT32
</TD>
<TD WIDTH=373 VALIGN=TOP>
'int32'
</TD>
</TR>
<TR>
<TD WIDTH=373 VALIGN=TOP>
NX_UINT32
</TD>
<TD WIDTH=373 VALIGN=TOP>
'uint32'
</TD>
</TR>
</THEAD>
</TABLE>
<p> <br> </p>
Here is simple example program that demonstrates the basic functions and most important differences between the C Nexus Api and the Python Nexus API.
<ol>
<li>Creates a NeXus file with access method HDF5</li>
<li>adds datagroups</li>
<li>makes a data array of data type NX_INT32</li>
<li>puts data to the array</li>
<li>reads the data and attributes</li>
<li>prints data and attribute value</li>
<li>closes the groups and the file.</li>
</ol>
<TABLE WIDTH=85% BORDER=1 CELLPADDING=4 CELLSPACING=3 ALIGN=CENTER style="background-color: rgb(238, 238, 238);" >
<COL WIDTH=376>
<THEAD>
<TR>
<TD WIDTH=376 VALIGN=TOP>
<pre>
import nxs,numpy
# Access method accepts strings or integer (e.g., nxs.ACC_CREATE5)
f = nxs.open("test.h5", 'w5')
f.makegroup("testgroup", "NXentry")
f.opengroup("testgroup", "NXentry")
f.makegroup("anothergroup", "NXentry")
# Some data to store in the file, this of type int16
data = numpy.array([[0,1,2,3],[4,5,6,7],[8,9,10,11],[12,13,14,15] ],'int16')
# Make a data set for the array. Note that this could also
# be done as f.makedata('data1','int16',[4,4])
f.makedata('data1', dtype=data.dtype, shape=data.shape)
f.opendata("data1")
f.putdata(data)
# Attribute type can be inferred from the data or specified. If inferred, it
# must match the type of the data. Attributes are scalars or strings, with
# string length inferred from value.
f.putattr('integer-attribute', 42, 'int16')
f.putattr('double-attribute', 3.14159)
f.closedata()
# NeXus returns arrays from getattr/getdata/getslab
f.opendata("data1")
print 'data :',f.getdata()
# getnext functions return tuples
attrname,length,type = f.getnextattr ()
value = f.getattr(attrname, length, type)
print 'first attribute: ', value
# ... or you can use iterators for attrs and entries
print 'all attributes'
for attr,value in f.attrs():
print " %s: %s"%(attr,value)
f.closedata()
f.closegroup()
f.close()
</pre>
</TD>
</TR>
</THEAD>
</TABLE>
</p>
<a name="NeXus API Routines"></a><h3> NeXus API Routines</h3>
<p>Documentation for the individual methods, and how they differ
from the basic NAPI methods is available from the Python command
line. Rather than duplicate it here, use the following in Python:
<TABLE WIDTH=85% BORDER=1 CELLPADDING=4 CELLSPACING=3 ALIGN=CENTER style="background-color: rgb(238, 238, 238);" >
<COL WIDTH=376>
<THEAD>
<TR>
<TD WIDTH=376 VALIGN=TOP>
<pre>
import nxs
help(nxs)
</pre>
</TD>
</TR>
</THEAD>
</TABLE>
</p>
</body></html>
|