Changeset 2068 for trunk/docs


Ignore:
Timestamp:
Nov 24, 2015 12:39:12 PM (8 years ago)
Author:
toby
Message:

cleanup image reader documetation

Location:
trunk/docs
Files:
1 added
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/docs/source/imports.rst

    r2027 r2068  
    33
    44Imports are implemented by deriving a class from
    5 :class:`GSASIIIO.ImportPhase`, :class:`GSASIIIO.ImportStructFactor`
     5:class:`GSASIIIO.ImportPhase`, :class:`GSASIIIO.ImportStructFactor`,
     6:class:`GSASIIIO.ImportPowderData`
    67or :class:`GSASIIIO.ImportPowderData` (which are in turn
    78derived from :class:`GSASIIIO.ImportBaseclass`)
    … …  
    2021.. _Import_routines:
    2122
    22 
    2323When writing a import routine, one should create a new class derived
    2424from :class:`GSASIIIO.ImportPhase`, :class:`GSASIIIO.ImportStructFactor`
    … …  
    2727an ``__init__()`` and a ``Reader()`` method, and most will supply a
    2828``ContentsValidator()`` method, too.
    29 See the :class:`~GSASIIIO.ImportPhase`, :class:`~GSASIIIO.ImportStructFactor`
    30 or :class:`~GSASIIIO.ImportPowderData` class documentation
     29See the :class:`~GSASIIIO.ImportPhase`,
     30:class:`~GSASIIIO.ImportStructFactor`,
     31:class:`~GSASIIIO.ImportPowderData`
     32or :class:`~GSASIIIO.ImportImage` class documentation
    3133for details on what values each type of ``Reader()`` should set.
    3234
    … …  
    3436~~~~~~~~~~~~~~
    3537 
    36 The class should supply a
    37 ``__init__`` method which calls the parent ``__init__`` method and
    38 specifies the following parameters:
    39 
    40   * `extensionlist`: a list of extensions that may be used for this type of file.
    41   * `strictExtension`: Should be True if only files with extensions in
    42     `extensionlist` are allows; False if all file types should be offered
     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
    4356    in the file browser. Also if False, the import class will be
    4457    used on all files when "guess from format" is tried, though
    45     readers with matching extensions will be tried first.
    46   * `formatName`: a string to be used in the menu. Should be short.
    47   * `longFormatName`: a longer string to be used to describe the format in help.
     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.
    4863
    4964Reader()
    … …  
    5772where the arguments have the following uses:
    5873
    59  * `filename`: a string with the name of the file being read
    60  * `filepointer`: a file object (created by :func:`open`) that accesses
     74 * ``filename``: a string with the name of the file being read
     75 * ``filepointer``: a file object (created by :func:`open`) that accesses
    6176   the file and is points to the beginning of the file when Reader is
    6277   called.
    63  * `ParentFrame`: a reference to the main GSAS-II (tree) windows, for
     78 * ``ParentFrame``: a reference to the main GSAS-II (tree) windows, for
    6479   the unusual ``Reader`` routines that will create GUI windows to ask
    65    questions.
     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.
    6683
    6784In addition, the following keyword parameters are defined that ``Reader``
    6885routines may optionally use:
    6986
    70  * `buffer`: a dict that can be used to retain information between repeated calls of the routine
    71  * `blocknum`: counts the number of times that a reader is called
    72  * `usedRanIdList`: a list of previously used random Id values that can be checked to determine that a value is unique.
    73 
    74 As an example, the `buffer` dict is used for CIF reading to hold the parsed CIF file
     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
    7594so that it can be reused without having to reread the file from
    7695scratch.
    … …  
    111130
    112131Set `self.repeat` to True (the default is False) if a Reader should be
    113 called again to read a second block from a file. Most commonly
    114 (only?) used for reading multiple powder histograms from a single
    115 file. Variable `self.repeatcount` is used to keep track of the block
    116 numbers.
     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.
    117136
    118137*support routines*
    … …  
    134153~~~~~~~~~~~~~~~~~~~~
    135154
     155.. _ContentsValidator:
     156
    136157Defining a ``ContentsValidator`` method is optional, but is usually a
    137158good idea, particularly if the file extension is not a reliable
    … …  
    251272-----------------------------------------------------
    252273Image import routines are classes derived from
    253 , :class:`GSASIIIO.ImportImage`.
    254 They must be found in files named `G2img*.py` that are in the Python path
    255 and the class must override the ``__init__`` method and add a ``Reader`` method.
     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
    256283The distributed routines are:
    257284
Note: See TracChangeset for help on using the changeset viewer.