From d188c2b72e9e016bb5ec20e0d6c97db874c8752b Mon Sep 17 00:00:00 2001 From: "donald e. boyce" Date: Tue, 5 Mar 2024 15:30:36 -0500 Subject: [PATCH] developer/API docs for imageseries --- docs/source/dev/imageseries-load-options.rst | 28 +++++- docs/source/dev/imageseries-overview.rst | 5 +- hexrd/imageseries/load/array.py | 28 +++--- hexrd/imageseries/load/hdf5.py | 38 +++----- hexrd/imageseries/omega.py | 1 - hexrd/imageseries/process.py | 23 ++--- hexrd/imageseries/save.py | 97 ++++++++++++-------- hexrd/imageseries/stats.py | 19 ++-- 8 files changed, 137 insertions(+), 102 deletions(-) diff --git a/docs/source/dev/imageseries-load-options.rst b/docs/source/dev/imageseries-load-options.rst index 528a4daf9..712941cdb 100644 --- a/docs/source/dev/imageseries-load-options.rst +++ b/docs/source/dev/imageseries-load-options.rst @@ -16,8 +16,10 @@ subtraction and flipping. **On Write.** ``path`` - (required) path to directory containing data group (data set is named - `images` + (required) path to directory containing data group + +``dataname`` + name of data set, default = "images" ``shuffle`` (default=True) HDF5 write option @@ -34,6 +36,11 @@ subtraction and flipping. (required) path to directory containing data group (data set is named `images`) +``dataname`` + name of data set, default = "images"; note that there is no actual + write option for this. + + Frame Cache ++++++++++++++++++++ The format name is ``frame-cache``. @@ -154,3 +161,20 @@ Here is an example that describes the GE format: bytes: 2 signed: false endian: little + + +Array +++++++ + +This loads a 3D numpy array and treats it as an imageseries. + +**On Write.** + +There is no writer for this format. + +**On Open.** + +``data`` + The 3-dimensional numpy array data. +``metadata`` + The metadata dictionary. diff --git a/docs/source/dev/imageseries-overview.rst b/docs/source/dev/imageseries-overview.rst index 859135c95..36ed31031 100644 --- a/docs/source/dev/imageseries-overview.rst +++ b/docs/source/dev/imageseries-overview.rst @@ -40,10 +40,11 @@ format. Possible formats currently are: ``raw-image`` This is for nonstandard or less common image formats that do not load with `fabio `. In that case, you can define - your own data format. + your own data format. This ``file`` argument is a YAML file. ``array`` - images are stored as a 3D numpy array; used for testing. + images are stored as a 3D numpy array; used for testing. It takes no + ``file`` argument, use ``None``. See also :ref:`keyword-options`. diff --git a/hexrd/imageseries/load/array.py b/hexrd/imageseries/load/array.py index 653856d0f..2f199057d 100644 --- a/hexrd/imageseries/load/array.py +++ b/hexrd/imageseries/load/array.py @@ -7,18 +7,20 @@ class ArrayImageSeriesAdapter(ImageSeriesAdapter): - """collection of images in numpy array""" - + """Collection of Images in numpy array + + Parameters + ---------- + fname: None + should be None + data: array (n, m, l) + 3-dimensional data array + metadata: dict (optional) + the metadata dictionary + """ format = 'array' def __init__(self, fname, **kwargs): - """Constructor for frame cache image series - - *fname* - should be None - *kwargs* - keyword arguments - . 'data' = a 3D array (double/float) - . 'metadata' = a dictionary - """ data_arr = np.array(kwargs['data']) if data_arr.ndim < 3: self._data = np.tile(data_arr, (1, 1, 1)) @@ -37,10 +39,7 @@ def __init__(self, fname, **kwargs): @property def metadata(self): - """(read-only) Image sequence metadata - - Currently returns none - """ + """Image sequence metadata""" return self._meta @property @@ -57,8 +56,5 @@ def __getitem__(self, key): def __iter__(self): return ImageSeriesIterator(self) - # @memoize def __len__(self): return self._nframes - - pass # end class diff --git a/hexrd/imageseries/load/hdf5.py b/hexrd/imageseries/load/hdf5.py index 14771ab9b..074c9f7b9 100644 --- a/hexrd/imageseries/load/hdf5.py +++ b/hexrd/imageseries/load/hdf5.py @@ -10,35 +10,23 @@ class HDF5ImageSeriesAdapter(ImageSeriesAdapter): - """collection of images in HDF5 format""" + """Collection of Images in HDF5 Format + + Parameters + ---------- + fname : str or h5py.File object + filename of the HDF5 file, or an open h5py file. Note that this + class will close the h5py.File when finished. + path : str, required + The path to the HDF dataset containing the image data + dataname : str, optional + The name of the HDF dataset containing the 2-d or 3d image data. + The default values is 'images'. + """ format = 'hdf5' def __init__(self, fname, **kwargs): - """ - Constructor for HDF% ImageSeries - - Parameters - ---------- - fname : str or h5py.File object - filename of the HDF5 file, or an open h5py file. Note that this - class will close the h5py.File when finished. - **kwargs : Keyword arguments - See below. - - Keyword Arguments - ----------------- - path : str, required - The path to the HDF dataset containing the image data - dataname : str, optional - The name of the HDF dataset containing the 2-d or 3d image data. - The default values is 'images'. - - Returns - ------- - None. - - """ if isinstance(fname, h5py.File): self.__h5name = fname.filename self.__h5file = fname diff --git a/hexrd/imageseries/omega.py b/hexrd/imageseries/omega.py index 4a8bef6f4..5480dc8cf 100644 --- a/hexrd/imageseries/omega.py +++ b/hexrd/imageseries/omega.py @@ -130,7 +130,6 @@ def omegarange_to_frames(self, omin, omax): class OmegaWedges(object): """piecewise linear omega ranges""" def __init__(self, nframes): - """Constructor for OmegaWedge""" self.nframes = nframes self._wedges = [] # diff --git a/hexrd/imageseries/process.py b/hexrd/imageseries/process.py index 02a0ef66a..c2101fc79 100644 --- a/hexrd/imageseries/process.py +++ b/hexrd/imageseries/process.py @@ -8,7 +8,18 @@ class ProcessedImageSeries(ImageSeries): - """Images series with mapping applied to frames""" + """imsageseries based on existing one with image processing options + + Parameters + ---------- + imser: ImageSeries + an existing imageseries + oplist: list + list of processing operations; each option is a (key, data) pair, + with key specifying the operation to perform using specified data + frame_list: list of ints or None, default = None + specify subset of frames by list; if None, then all frames are used + """ FLIP = 'flip' DARK = 'dark' RECT = 'rectangle' @@ -16,17 +27,7 @@ class ProcessedImageSeries(ImageSeries): GAUSS_LAPLACE = 'gauss_laplace' def __init__(self, imser, oplist, **kwargs): - """imsageseries based on existing one with image processing options - *imser* - an existing imageseries - *oplist* - list of processing operations; - a list of pairs (key, data) pairs, with key specifying the - operation to perform using specified data - - *keyword args* - 'frame_list' - specify subset of frames by list - - """ self._imser = imser self._meta = copy.deepcopy(imser.metadata) self._oplist = oplist diff --git a/hexrd/imageseries/save.py b/hexrd/imageseries/save.py index 0de243f51..187b5fc67 100644 --- a/hexrd/imageseries/save.py +++ b/hexrd/imageseries/save.py @@ -24,10 +24,16 @@ def write(ims, fname, fmt, **kwargs): """write imageseries to file with options - *ims* - an imageseries - *fname* - name of file or an h5py file for writing HDF5 - *fmt* - a format string - *kwargs* - options specific to format + Parameters + ---------- + ims: Imageseries + the imageseries to write + fname: str + the name of the HDF5 file to write + fmt: str + format name of the imageseries + kwargs: dict + options specific to format """ wcls = _Registry.getwriter(fmt) w = wcls(ims, fname, **kwargs) @@ -61,7 +67,17 @@ def getwriter(cls, name): class Writer(object, metaclass=_RegisterWriter): - """Base class for writers""" + """Base class for writers + + Parameters + ---------- + ims: Imageseries + the imageseries to write + fname: str + the name of the HDF5 file to write + kwargs: dict + options specific to format + """ fmt = None def __init__(self, ims, fname, **kwargs): @@ -98,21 +114,29 @@ def opts(self): return self._opts class WriteH5(Writer): + """Write imageseries in HDF5 file + + Parameters + ---------- + ims: Imageseries + the imageseries to write + fname: str + the name of the HDF5 file to write + path: str, required + the path in HDF5 file + gzip: int 0-9 + 0 turns off compression, default=1 + chunk_rows: int + number of rows per chunk; default is all + shuffle: bool + shuffle HDF5 data + """ fmt = 'hdf5' dflt_gzip = 1 dflt_chrows = 0 dflt_shuffle = True def __init__(self, ims, fname, **kwargs): - """Write imageseries in HDF5 file - - Required Args: - path - the path in HDF5 file - - Options: - gzip - 0-9; 0 turns off compression; 4 is default - chunk_rows - number of rows per chunk; default is all - """ Writer.__init__(self, ims, fname, **kwargs) self._path = self._opts['path'] @@ -173,32 +197,31 @@ def h5opts(self): class WriteFrameCache(Writer): - """info from yml file""" + """write frame cache imageseries + + The default write option is to save image data and metadata all + in a single npz file. The original option was to have a YAML file + as the primary file and a specified cache file for the images; this + method is deprecated. + + Parameters + ---------- + ims: Imageseries instance + the imageseries to write + fname: str or Path + name of file to write; + threshold: float + threshold value for image, at or below which values are zeroed + cache_file: str or Path, optional + name of the npz file to save the image data, if not given in the + `fname` argument; for YAML format (deprecated), this is required + max_workers: int, optional + The max number of worker threads for multithreading. Defaults to + the number of CPUs. + """ fmt = 'frame-cache' def __init__(self, ims, fname, **kwargs): - """write yml file with frame cache info - - The default write option is to save image data and metadata all - in a single npz file. The original option was to have a YAML file - as the primary file and a specified cache file for the images; this - method is deprecated. - - Parameters - ---------- - ims: Imageseries instance - the imageseries to write - fname: str or Path - name of file to write; - threshold: float - threshold value for image, at or below which values are zeroed - cache_file: str or Path, optional - name of the npz file to save the image data, if not given in the - `fname` argument; for YAML format (deprecated), this is required - max_workers: int, optional - The max number of worker threads for multithreading. Defaults to - the number of CPUs. - """ Writer.__init__(self, ims, fname, **kwargs) self._thresh = self._opts['threshold'] self._cache, self.cachename = self._set_cache() diff --git a/hexrd/imageseries/stats.py b/hexrd/imageseries/stats.py index ab0744c82..6f5f7eef3 100644 --- a/hexrd/imageseries/stats.py +++ b/hexrd/imageseries/stats.py @@ -1,4 +1,4 @@ -"""aggregate statistics for imageseries +"""Aggregate Statistics for Imageseries The functions here operate on the frames of an imageseries and return a single aggregate image. For each function, there is a corresponding iterable @@ -8,15 +8,18 @@ For example: -# Using the standard function call -img = stats.average(ims) +.. code-block:: python -# Using the iterable with 10 chunks -for img in stats.average_iter(ims, 10): - # update progress bar - pass + # Using the standard function call + img = stats.average(ims) -NOTE: + # Using the iterable with 10 chunks + for img in stats.average_iter(ims, 10): + # update progress bar + pass + +NOTES +----- * Perhaps we should rename min -> minimum and max -> maximum to avoid conflicting with the python built-ins """