Changeset 2068


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

cleanup image reader documetation

Location:
trunk
Files:
1 added
1 deleted
11 edited

Legend:

Unmodified
Added
Removed

  • trunk/GSASII.py

    r2065 r2068  
    782782                first = False
    783783                self.CheckNotebook()
     784            rd.Data['ImageTag'] = rd.repeatcount
    784785            G2IO.LoadImage2Tree(rd.readfilename,self,rd.Comments,rd.Data,rd.Npix,rd.Image)
    785786        self.PatternTree.SelectItem(G2gd.GetPatternTreeItemId(self,self.Image,'Image Controls'))             #show last image to have beeen read

  • trunk/GSASIIIO.py

    r2065 r2068  
    496496                    print 'Transposing Image!'
    497497                    rd.Image = rd.Image.T
     498                rd.Data['ImageTag'] = rd.repeatcount
    498499                LoadImage2Tree(imagefile,G2frame,rd.Comments,rd.Data,rd.Npix,rd.Image)
    499500                repeat = rd.repeat
    … …  
    722723        return head,data,Npix,image
    723724       
    724 # should get moved to importer when ready to test
    725 def GetPNGData(filename,imageOnly=False):
    726     '''Read an image in a png format, assumes image is converted from CheMin tif file
    727     so default parameters are that machine.
    728     '''
    729     import scipy.misc
    730     Image = scipy.misc.imread(filename,flatten=True)
    731     Npix = Image.size
    732     Comments = ['no metadata']
    733     pixy = list(Image.shape)
    734     sizexy = [40,40]
    735     Data = {'wavelength': 1.78892, 'pixelSize': sizexy, 'distance': 18.0,'size':pixy}
    736     Data['center'] = [pixy[0]*sizexy[0]/1000,pixy[1]*sizexy[1]/2000]
    737     if imageOnly:
    738         return Image.T
    739     else:
    740         return Comments,Data,Npix,Image.T
    741    
    742725def ProjFileOpen(G2frame):
    743726    'Read a GSAS-II project file and load into the G2 data tree'
    … …  
    16511634    '''Defines a base class for the reading of images
    16521635
    1653     Images are intially read with a call to :meth:`GSASII.GSASII.OnImportImage`
    1654     which in turn calls :meth:`GSASII.GSASII.OnImportGeneric`, which calls
    1655     methods :meth:`ExtensionValidator`, :meth:`ContentsValidator` and
    1656     :meth:`Reader`. Images are also reread with :func:`GSASIIIO.GetImageData`
    1657 
    1658     See :ref:`Writing a Import Routine<Import_Routines>`
    1659     for an explanation on how to use import classes in general. The specifics
    1660     for reading an image requires that the ``Reader()`` routine in the import
    1661     class should set:
     1636    Images are read in only these places:
    16621637   
    1663       * :attr:`Comments` (a list of strings),
    1664       * :attr:`Data` (a dict defining image parameters),
    1665       * :attr:`Npix` (the number of pixels in the image)
    1666       * :attr:`Image` (the actual image)
    1667       * optionally: :attr:`repeat` (set to True if there are additional images to
    1668         read in the file)
    1669      
     1638      * Initial reading is typically done from a menu item
     1639        with a call to :meth:`GSASII.GSASII.OnImportImage`
     1640        which in turn calls :meth:`GSASII.GSASII.OnImportGeneric`. That calls
     1641        methods :meth:`ExtensionValidator`, :meth:`ContentsValidator` and
     1642        :meth:`Reader`. This returns a list of reader objects for each read image.
     1643
     1644      * Images are read alternatively in :func:`GSASIIIO.ReadImages`, which puts image info
     1645        directly into the data tree.
     1646
     1647      * Images are reloaded with :func:`GSASIIIO.GetImageData`.
     1648
     1649    .. _Image_import_routines:
     1650
     1651    When reading an image, the ``Reader()`` routine in the ImportImage class
     1652    should set:
     1653   
     1654      * :attr:`Comments`: a list of strings (str),
     1655      * :attr:`Npix`: the number of pixels in the image (int),
     1656      * :attr:`Image`: the actual image as a numpy array (np.array)
     1657      * :attr:`Data`: a dict defining image parameters (dict). Within this dict the following
     1658        data items are needed:
     1659       
     1660         * 'pixelSize': size of each pixel in microns (such as ``[200,200]``.
     1661         * 'wavelength': wavelength in Angstoms.
     1662         * 'distance': distance of detector from sample in cm.
     1663         * 'center': uncalibrated center of beam on detector (such as ``[204.8,204.8]``.
     1664         * 'size': size of image (such as ``[2048,2048]``).
     1665         * 'ImageTag': image number or other keyword used to retrieve image from
     1666           a multi-image data file (defaults to ``1`` if not specified).
     1667
     1668    optional data items:
     1669   
     1670      * :attr:`repeat`: set to True if there are additional images to
     1671        read in the file, False otherwise
     1672      * :attr:`repeatcount`: set to the number of the image.
    16701673     
    16711674    Note that the above is initialized with :meth:`InitParameters`.
     1675    (Also see :ref:`Writing a Import Routine<Import_Routines>`
     1676    for an explanation on how to use import classes in general.)
    16721677    '''
    16731678    def __init__(self,formatName,longFormatName=None,extensionlist=[],
    … …  
    16891694        self.Image = None
    16901695        self.repeat = False
     1696        self.repeatcount = 1
    16911697
    16921698    def LoadImage(self,ParentFrame,imagefile,imagetag=None):

  • 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

  • trunk/imports/G2img_1TIF.py

    r2065 r2068  
    88########### SVN repository information ###################
    99'''
    10 *Module G2img_TIF: .tif image file*
    11 --------------------------------------
     10*Module G2img_1TIF: Tagged-image File images*
     11--------------------------------------------------
    1212
    1313Routine to read an image in Tagged-image file (TIF) format as well as a variety
    14 of slightly incorrect pseudo-TIF formats used at instruments around the world.
     14of slightly incorrect pseudo-TIF formats used at instruments around the world.
     15Note that the name ``G2img_1TIF`` is used so that this file will
     16sort to the top of the image formats and thus show up first in the menu.
     17(It is the most common, alas).
    1518
    1619'''
    … …  
    2528GSASIIpath.SetVersionNumber("$Revision: $")
    2629class TIF_ReaderClass(G2IO.ImportImage):
    27     '''Routine to read an image in Tagged-image file (TIF) format as well as a variety
    28     of slightly incorrect pseudo-TIF formats
     30    '''Reads TIF files using a routine (:func:`GetTifData`) that looks
     31    for files that can be identified from known instruments and will
     32    correct for slightly incorrect TIF usage. If that routine fails,
     33    it will be read with a standard TIF reader, which can handle compression
     34    and other things less commonly used at beamlines.
    2935    '''
    3036    def __init__(self):
    … …  
    4955   
    5056    def Reader(self,filename,filepointer, ParentFrame=None, **unused):
    51         '''Read the TIF file using Bob's routine
     57        '''Read the TIF file using :func:`GetTifData`. If that fails,
     58        use :func:`scipy.misc.imread` and give the user a chance to
     59        edit the likely wrong default image parameters.
    5260        '''
    5361       

  • trunk/imports/G2img_ADSC.py

    r2015 r2068  
    1111--------------------------------------
    1212
    13 Routine to read an ADSC .img file
    14 
    1513'''
    1614
    … …  
    2119GSASIIpath.SetVersionNumber("$Revision: $")
    2220class ADSC_ReaderClass(G2IO.ImportImage):
     21    '''Reads an ADSC .img file
     22    '''
    2323    def __init__(self):
    2424        super(self.__class__,self).__init__( # fancy way to self-reference
    … …  
    3535       
    3636    def Reader(self,filename,filepointer, ParentFrame=None, **unused):
    37         '''Read using Bob's routine
     37        '''Read using Bob's routine :func:`GSASIIIO.GetImgData`
     38        (to be moved to this file, eventually)
    3839        '''
    3940        self.Comments,self.Data,self.Npix,self.Image = G2IO.GetImgData(filename)

  • trunk/imports/G2img_CheMin.py

    r2015 r2068  
    1212
    1313Routine to read an image in .png (Portable Network Graphics) format.
    14 For now, the only known use of this is with converted CheMin tif files
    15 so default parameters are that machine.
     14For now, the only known use of this is with converted Mars Rover (CheMin)
     15tif files, so default parameters are for that.
    1616
    1717'''
    … …  
    2323GSASIIpath.SetVersionNumber("$Revision: $")
    2424class png_ReaderClass(G2IO.ImportImage):
     25    '''Reads standard PNG images; parameters are set to those of the
     26    Mars Rover (CheMin) diffractometer.
     27    '''
    2528    def __init__(self):
    2629        super(self.__class__,self).__init__( # fancy way to self-reference
    … …  
    3740       
    3841    def Reader(self,filename,filepointer, ParentFrame=None, **unused):
    39         '''Read using scipy PNG reader
     42        '''Reads using standard scipy PNG reader
    4043        '''
    4144        import scipy.misc
    … …  
    5356        self.LoadImage(ParentFrame,filename)
    5457        return True
    55 # N.B. This replaces G2IO.GetPNGData

  • trunk/imports/G2img_EDF.py

    r2015 r2068  
    1111--------------------------------------
    1212
    13 Routine to read a Read European detector data edf file
    14 
    1513'''
    1614
    … …  
    2119GSASIIpath.SetVersionNumber("$Revision: $")
    2220class EDF_ReaderClass(G2IO.ImportImage):
     21    '''Routine to read a Read European detector data .edf file.
     22    This is a particularly nice standard.
     23    '''
    2324    def __init__(self):
    2425        super(self.__class__,self).__init__( # fancy way to self-reference
    … …  
    2930            )
    3031
    31     def ContentsValidator(self, filepointer):
    32        
    33         '''no test at this time
     32    def ContentsValidator(self, filepointer):       
     33        '''no test used at this time
    3434        '''
    3535        return True
    3636       
    3737    def Reader(self,filename,filepointer, ParentFrame=None, **unused):
    38         '''Read using Bob's routine
     38        '''Read using Bob's routine :func:`GSASIIIO.GetEdfData`
     39        (to be moved to this file, eventually)
    3940        '''
    4041        self.Comments,self.Data,self.Npix,self.Image = G2IO.GetEdfData(filename)

  • trunk/imports/G2img_GE.py

    r2065 r2068  
    1111---------------------------------------
    1212
    13 Routine to read a summed GE image from APS Sector 1
     13This shows an example of an importer that will handle files with
     14more than a single image.
    1415
    1516'''
    … …  
    2223GSASIIpath.SetVersionNumber("$Revision: $")
    2324class GEsum_ReaderClass(G2IO.ImportImage):
     25    '''Routine to read a GE image, typically from APS Sector 1.
     26       
     27        The image files may be of form .geX (where X is ' ', 1, 2, 3 or 4),
     28        which is a raw image from the detector. These files may contain more
     29        than one image and have a rudimentary header.
     30        Files with extension .sum or .cor are 4 byte integers/pixel, one image/file.
     31        Files with extension .avg are 2 byte integers/pixel, one image/file.
     32    '''
     33
    2434    def __init__(self):
    2535        super(self.__class__,self).__init__( # fancy way to self-reference
    … …  
    3646       
    3747    def Reader(self,filename,filepointer, ParentFrame=None, **kwarg):
    38         '''Read using GE file reader
     48        '''Read using GE file reader, :func:`GetGEsumData`
    3949        '''
    4050        #rdbuffer = kwarg.get('buffer')
    … …  
    95105    image = np.reshape(image,(sizexy[1],sizexy[0]))
    96106    data = {'pixelSize':[200,200],'wavelength':0.15,'distance':250.0,'center':[204.8,204.8],'size':sizexy}
    97     data['ImageTag'] = imagenum
     107    self.repeatcount = imagenum
    98108    File.close()
    99109    if GSASIIpath.GetConfigValue('debug'):

  • trunk/imports/G2img_MAR.py

    r2015 r2068  
    1111--------------------------------------
    1212
    13 Routine to read several MAR formats, .mar3450,.mar2300,.mar2560
    14 
    1513'''
    1614
    … …  
    2119GSASIIpath.SetVersionNumber("$Revision: $")
    2220class MAR_ReaderClass(G2IO.ImportImage):
     21    '''Routine to read several MAR formats, .mar3450,.mar2300,.mar2560
     22    '''
    2323    def __init__(self):
    2424        super(self.__class__,self).__init__( # fancy way to self-reference
    … …  
    3535       
    3636    def Reader(self,filename,filepointer, ParentFrame=None, **unused):
    37         '''Read using Bob's routine
     37        '''Read using Bob's routine :func:`GSASIIIO.GetMAR345Data`
     38        (to be moved to this file, eventually)
    3839        '''
    3940        self.Comments,self.Data,self.Npix,self.Image = G2IO.GetMAR345Data(filename)

  • trunk/imports/G2img_Rigaku.py

    r2054 r2068  
    1111--------------------------------------
    1212
    13 Routine to read a Rigaku R-Axis IV image file
    14 
    1513'''
    1614
    … …  
    2119GSASIIpath.SetVersionNumber("$Revision: $")
    2220class Rigaku_ReaderClass(G2IO.ImportImage):
     21    '''Routine to read a Rigaku R-Axis IV image file.
     22    '''
    2323    def __init__(self):
    2424        super(self.__class__,self).__init__( # fancy way to self-reference
    … …  
    2929            )
    3030
    31     def ContentsValidator(self, filepointer):
    32        
    33         '''Does the file size make sense?
     31    def ContentsValidator(self, filepointer):       
     32        '''Test by checking if the file size makes sense.
    3433        '''
    3534        fileSize = os.stat(filepointer.name).st_size
    … …  
    4039       
    4140    def Reader(self,filename,filepointer, ParentFrame=None, **unused):
    42         '''Read using Bob's routine
     41        '''Read using Bob's routine :func:`GSASIIIO.GetRigaku`
     42        (to be moved to this file, eventually)
    4343        '''
    4444

  • trunk/imports/G2img_SumG2.py

    r2065 r2068  
    88########### SVN repository information ###################
    99'''
    10 *Module G2img_G2: Python pickled image*
    11 ---------------------------------------
    12 
    13 Routine to read an image that has been pickled in Python. Images
    14 in this format are created by the "Sum image data" command.
     10*Module G2img_SumG2: Python pickled image*
     11------------------------------------------
    1512
    1613'''
    … …  
    2320GSASIIpath.SetVersionNumber("$Revision: $")
    2421class G2_ReaderClass(G2IO.ImportImage):
     22    '''Routine to read an image that has been pickled in Python. Images
     23    in this format are created by the "Sum image data" command. At least for
     24    now, only one image is permitted per file.
     25    '''
    2526    def __init__(self):
    2627        super(self.__class__,self).__init__( # fancy way to self-reference
    … …  
    3233
    3334    def ContentsValidator(self, filepointer):
    34         '''no test at this time
     35        '''test by trying to unpickle (should be quick)
    3536        '''
     37        try:
     38            Fp = open(filename,'rb')
     39            cPickle.load(Fp)
     40        except:
     41            return False
    3642        return True
    3743       
    3844    def Reader(self,filename,filepointer, ParentFrame=None, **unused):
    39         '''Read using scipy PNG reader
     45        '''Read using cPickle
    4046        '''
    4147        import scipy.misc
Note: See TracChangeset for help on using the changeset viewer.