source: trunk/docs/source/imports.rst @ 2068

Last change on this file since 2068 was 2068, checked in by toby, 7 years ago

cleanup image reader documetation

File size: 10.9 KB
Line 
1*GSAS-II Import Modules*
2====================================
3
4Imports are implemented by deriving a class from
5:class:`GSASIIIO.ImportPhase`, :class:`GSASIIIO.ImportStructFactor`,
6:class:`GSASIIIO.ImportPowderData`
7or :class:`GSASIIIO.ImportPowderData` (which are in turn
8derived from :class:`GSASIIIO.ImportBaseclass`)
9to implement import of
10a phase, a single crystal or a powder dataset, respectively.
11Module file names (`G2phase_`, `G2pwd_` and `G2sfact_`, etc.) are used to
12determine which menu an import routine should be placed into. (N.B. this
13was an unnecessary choice; this could be done from the class used.)
14
15This list may not include all currently defined formats, since modules
16may be loaded from anywhere in the path.
17
18Writing an Import Routine
19--------------------------
20
21.. _Import_routines:
22
23When writing a import routine, one should create a new class derived
24from :class:`GSASIIIO.ImportPhase`, :class:`GSASIIIO.ImportStructFactor`
25or :class:`GSASIIIO.ImportPowderData`. As described below,
26all these classes will implement
27an ``__init__()`` and a ``Reader()`` method, and most will supply a
28``ContentsValidator()`` method, too.
29See the :class:`~GSASIIIO.ImportPhase`,
30:class:`~GSASIIIO.ImportStructFactor`,
31:class:`~GSASIIIO.ImportPowderData`
32or :class:`~GSASIIIO.ImportImage` class documentation
33for details on what values each type of ``Reader()`` should set.
34
35__init__()
36~~~~~~~~~~~~~~
37 
38The ``__init__`` method will follow standard boilerplate:
39
40.. code-block:: python
41
42    def __init__(self):
43        super(self.__class__,self).__init__( # fancy way to self-reference
44            extensionlist=('.ext1','ext2'),
45            strictExtension=True,
46            formatName = 'example image',
47            longFormatName = 'A longer description that this is an example image format'
48            )
49
50The first line in the ``__init__`` method calls the parent class
51``__init__`` method with the following parameters:
52
53  * ``extensionlist``: a list of extensions that may be used for this type of file.
54  * ``strictExtension``: Should be True if only files with extensions in
55    ``extensionlist`` are allows; False if all file types should be offered
56    in the file browser. Also if False, the import class will be
57    used on all files when "guess from format" is tried, though
58    readers with matching extensions will be tried first.
59    It is a very good idea to supply  a :ref:`ContentsValidator <ContentsValidator>`
60    method when ``strictExtension`` is False.
61  * ``formatName``: a string to be used in the menu. Should be short.
62  * ``longFormatName``: a longer string to be used to describe the format in help.
63
64Reader()
65~~~~~~~~~~~~~~
66
67The class must supply a ``Reader`` method that actually performs the
68reading. All readers must have at a minimum these arguments::
69
70    def Reader(self, filename, filepointer, ParentFrame, **unused):
71
72where the arguments have the following uses:
73
74 * ``filename``: a string with the name of the file being read
75 * ``filepointer``: a file object (created by :func:`open`) that accesses
76   the file and is points to the beginning of the file when Reader is
77   called.
78 * ``ParentFrame``: a reference to the main GSAS-II (tree) windows, for
79   the unusual ``Reader`` routines that will create GUI windows to ask
80   questions. The Reader should do something reasonable such as take a
81   reasonable default if ``ParentFrame`` is None, which indicates that
82   GUI should not be accessed.
83
84In addition, the following keyword parameters are defined that ``Reader``
85routines may optionally use:
86
87 * ``buffer``: a dict that can be used to retain information between repeated calls of the routine
88 * ``blocknum``: counts the number of times that a reader is called, to
89   be used with files that contain more than one set of data (e.g. GSAS
90   .gsa/.fxye files with multiple banks or image files with multiple images.)
91 * ``usedRanIdList``: a list of previously used random Id values that can be checked to determine that a value is unique.
92
93As an example, the ``buffer`` dict is used in CIF reading to hold the parsed CIF file
94so that it can be reused without having to reread the file from
95scratch.
96
97Reader return values
98______________________
99
100The ``Reader`` routine should return the value of True if the file has been
101read successfully. Optionally, use `self.warnings` to indicate any
102problems.
103
104If the file cannot be read,  the ``Reader`` routine should
105return False or raise an :class:`GSASIIIO.ImportBaseclass.ImportException`
106exception. (Why either? Sometimes an exception is the easiest way to
107bail out of a called routine.) Place text in `self.errors` and/or use::
108
109     ImportException('Error message')
110
111to give the user information on what went wrong during the reading.
112
113self.warnings
114_____________________
115
116Use `self.warnings` to indicate any information
117that should be displayed to the user if the file is read successfully,
118but perhaps not completely or additional settings will need to be
119made.
120
121self.errors
122_____________________
123
124Use `self.errors` to give the user information on where and why a read
125error occurs in the file. Note that text supplied with the ``raise``
126statement will be appended to ``self.errors``.
127
128self.repeat
129_____________________
130
131Set `self.repeat` to True (the default is False) if a Reader should be
132called again to after reading to indicate that more data may exist in
133the file to be read. This is used for reading multiple powder
134histograms or multiple images from a single file. Variable
135`self.repeatcount` is used to keep track of the block numbers.
136
137*support routines*
138_________________________
139
140Note that the base class (:class:`GSASIIIO.ImportBaseclass`) supplies two routines,
141:meth:`~GSASIIIO.ImportBaseclass.BlockSelector` and
142:meth:`~GSASIIIO.ImportBaseclass.MultipleBlockSelector` that are useful for
143selecting amongst one or more datasets (and perhaps phases) for
144``Reader()`` routines that may encounter more than one set of information
145in a file.
146Likewise, when an operation will take some time to complete,
147use :meth:`~GSASIIIO.ImportBaseclass.ShowBusy` and
148:meth:`~GSASIIIO.ImportBaseclass.DoneBusy` to show the user
149that something is happening.
150
151
152ContentsValidator()
153~~~~~~~~~~~~~~~~~~~~
154
155.. _ContentsValidator:
156
157Defining a ``ContentsValidator`` method is optional, but is usually a
158good idea, particularly if the file extension is not a reliable
159identifier for the file type. The intent of this routine is to take a
160superficial look at the file to see if it has the expected
161characteristics of the expected file type. For example, are there
162numbers in the expected places?
163
164This routine is passed a single argument:
165
166* `filepointer`: a file object (created by :func:`open`) that accesses
167  the file and is points to the beginning of the file when ContentsValidator is
168  called.
169
170Note that :meth:`GSASIIIO.ImportBaseclass.CIFValidator` is a ContentsValidator
171for validating CIF files.
172
173
174ReInitialize()
175~~~~~~~~~~~~~~~~~~~~
176
177Import classes are substantiated only once and are used as needed.
178This means that if something needs to be initialized before the
179``Reader()`` will be called to read a new file, it must be coded. The
180``ReInitialize()`` method is provided for this and it is always called
181before the ``ContentsValidator`` method is called. Use care to call
182the parent class ``ReInitialize()`` method, if this is overridden.
183
184
185ContentsValidator return values
186________________________________
187
188The ``ContentsValidator`` routine should return the value of True if
189the file appears to match the type expected for the class.
190
191If the file cannot be read by this class,  the routine should
192return False. Preferably one will also place text in `self.errors` 
193to give the user information on what went wrong during the reading.
194
195Phase Import Routines
196----------------------------------------
197Phase import routines are classes derived from
198:class:`GSASIIIO.ImportPhase`
199They must be found in files named `G2phase*.py` that are in the Python path
200and the class must override the ``__init__`` method and add a ``Reader`` method.
201The distributed routines are:
202
203.. automodule:: G2phase
204    :members: 
205    :synopsis: Uses previously implemented code: PDB and GSAS .EXP
206
207.. automodule:: G2phase_GPX
208    :members: 
209    :synopsis: Reads phase information from a GSAS-II project (.gpx) file
210      a text file.
211
212.. automodule:: G2phase_CIF
213    :members: 
214    :synopsis: Reads phase information from a CIF
215
216Powder Data Import Routines
217---------------------------------------------
218Powder data import routines are classes derived from
219:class:`GSASIIIO.ImportPowderData`.
220They must be found in files named `G2pwd*.py` that are in the Python path
221and the class must override the ``__init__`` method and add a
222``Reader`` method.
223
224The distributed routines are:
225
226.. automodule:: G2pwd_GPX
227    :members: 
228    :synopsis: Reads powder data from from a GSAS-II project (.gpx) file
229
230.. automodule:: G2pwd_fxye
231    :members: 
232    :synopsis: Reads powder data in all of the GSAS formats
233
234.. automodule:: G2pwd_xye
235    :members: 
236    :synopsis: Reads powder data from a Topas format file
237
238.. automodule:: G2pwd_CIF
239    :members: 
240    :synopsis: Reads powder data from a CIF
241
242Single Crystal Data Import Routines
243-----------------------------------------------------
244Single crystal data import routines are classes derived from
245, :class:`GSASIIIO.ImportStructFactor`.
246They must be found in files named `G2sfact*.py` that are in the Python path
247and the class must override the ``__init__`` method and add a ``Reader`` method.
248The distributed routines are:
249
250.. automodule:: G2sfact
251    :members: 
252    :synopsis: Reads single crystal data from simple hkl files
253
254.. automodule:: G2sfact_CIF
255    :members: 
256    :synopsis: Reads single crystal data from CIF files
257
258
259Small Angle Scattering Data Import Routines
260-----------------------------------------------------
261Small angle scattering data import routines are classes derived from
262, :class:`GSASIIIO.ImportSmallAngle`.
263They must be found in files named `G2sad*.py` that are in the Python path
264and the class must override the ``__init__`` method and add a ``Reader`` method.
265The distributed routines are:
266
267.. automodule:: G2sad_xye
268    :members: 
269    :synopsis: Reads small angle scattering data from simple files
270
271Image Import Routines
272-----------------------------------------------------
273Image import routines are classes derived from
274:class:`GSASIIIO.ImportImage`.
275See :ref:`Writing a Import Routine<Import_Routines>` for general
276information on importers and
277:ref:`the ImportImage docstring<Image_import_routines>`
278for what a reader should define.
279Image importers must be found in files named `G2img*.py` that are in the Python path
280and the class must override the ``__init__`` method and add a
281``Reader`` method.
282
283The distributed routines are:
284
285.. automodule:: G2img_ADSC
286    :members: 
287
288.. automodule:: G2img_EDF
289    :members: 
290
291.. automodule:: G2img_SumG2
292    :members: 
293
294.. automodule:: G2img_GE
295    :members: 
296
297.. automodule:: G2img_MAR
298    :members: 
299
300.. automodule:: G2img_Rigaku
301    :members: 
302
303.. automodule:: G2img_1TIF
304    :members: 
305
306.. automodule:: G2img_CheMin
307    :members: 
Note: See TracBrowser for help on using the repository browser.