pyiqa.data.data_util
====================

.. py:module:: pyiqa.data.data_util




Module Contents
---------------

.. py:function:: read_img_seq(path, require_mod_crop=False, scale=1, return_imgname=False)

   Read a sequence of images from a given folder path.

   :param path: List of image paths or image folder path.
   :type path: list[str] | str
   :param require_mod_crop: Require mod crop for each image.
                            Default: False.
   :type require_mod_crop: bool
   :param scale: Scale factor for mod_crop. Default: 1.
   :type scale: int
   :param return_imgname: Whether return image names. Default False.
   :type return_imgname: bool

   :returns: size (t, c, h, w), RGB, [0, 1].
             list[str]: Returned image name list.
   :rtype: Tensor


.. py:function:: generate_frame_indices(crt_idx, max_frame_num, num_frames, padding='reflection')

   Generate an index list for reading `num_frames` frames from a sequence
   of images.

   :param crt_idx: Current center index.
   :type crt_idx: int
   :param max_frame_num: Max number of the sequence of images (from 1).
   :type max_frame_num: int
   :param num_frames: Reading num_frames frames.
   :type num_frames: int
   :param padding: Padding mode, one of
                   'replicate' | 'reflection' | 'reflection_circle' | 'circle'
                   Examples: current_idx = 0, num_frames = 5
                   The generated frame indices under different padding mode:
                   replicate: [0, 0, 0, 1, 2]
                   reflection: [2, 1, 0, 1, 2]
                   reflection_circle: [4, 3, 0, 1, 2]
                   circle: [3, 4, 0, 1, 2]
   :type padding: str

   :returns: A list of indices.
   :rtype: list[int]


.. py:function:: paired_paths_from_lmdb(folders, keys)

   Generate paired paths from lmdb files.

   Contents of lmdb. Taking the `lq.lmdb` for example, the file structure is:

   lq.lmdb
   ├── data.mdb
   ├── lock.mdb
   ├── meta_info.txt

   The data.mdb and lock.mdb are standard lmdb files and you can refer to
   https://lmdb.readthedocs.io/en/release/ for more details.

   The meta_info.txt is a specified txt file to record the meta information
   of our datasets. It will be automatically created when preparing
   datasets by our provided dataset tools.
   Each line in the txt file records
   1)image name (with extension),
   2)image shape,
   3)compression level, separated by a white space.
   Example: `baboon.png (120,125,3) 1`

   We use the image name without extension as the lmdb key.
   Note that we use the same key for the corresponding lq and gt images.

   :param folders: A list of folder path. The order of list should
                   be [input_folder, gt_folder].
   :type folders: list[str]
   :param keys: A list of keys identifying folders. The order should
                be in consistent with folders, e.g., ['lq', 'gt'].
                Note that this key is different from lmdb keys.
   :type keys: list[str]

   :returns: Returned path list.
   :rtype: list[str]


.. py:function:: paired_paths_from_meta_info_file(folders, keys, meta_info_file, filename_tmpl)

   Generate paired paths from an meta information file.

   Each line in the meta information file contains the image names and
   image shape (usually for gt), separated by a white space.

   Example of an meta information file:
   ```
   0001_s001.png (480,480,3)
   0001_s002.png (480,480,3)
   ```

   :param folders: A list of folder path. The order of list should
                   be [input_folder, gt_folder].
   :type folders: list[str]
   :param keys: A list of keys identifying folders. The order should
                be in consistent with folders, e.g., ['lq', 'gt'].
   :type keys: list[str]
   :param meta_info_file: Path to the meta information file.
   :type meta_info_file: str
   :param filename_tmpl: Template for each filename. Note that the
                         template excludes the file extension. Usually the filename_tmpl is
                         for files in the input folder.
   :type filename_tmpl: str

   :returns: Returned path list.
   :rtype: list[str]


.. py:function:: paired_paths_from_folder(folders, keys, filename_tmpl)

   Generate paired paths from folders.

   :param folders: A list of folder path. The order of list should
                   be [input_folder, gt_folder].
   :type folders: list[str]
   :param keys: A list of keys identifying folders. The order should
                be in consistent with folders, e.g., ['lq', 'gt'].
   :type keys: list[str]
   :param filename_tmpl: Template for each filename. Note that the
                         template excludes the file extension. Usually the filename_tmpl is
                         for files in the input folder.
   :type filename_tmpl: str

   :returns: Returned path list.
   :rtype: list[str]


.. py:function:: paths_from_folder(folder)

   Generate paths from folder.

   :param folder: Folder path.
   :type folder: str

   :returns: Returned path list.
   :rtype: list[str]


.. py:function:: paths_from_lmdb(folder)

   Generate paths from lmdb.

   :param folder: Folder path.
   :type folder: str

   :returns: Returned path list.
   :rtype: list[str]


.. py:function:: generate_gaussian_kernel(kernel_size=13, sigma=1.6)

   Generate Gaussian kernel used in `duf_downsample`.

   :param kernel_size: Kernel size. Default: 13.
   :type kernel_size: int
   :param sigma: Sigma of the Gaussian kernel. Default: 1.6.
   :type sigma: float

   :returns: The Gaussian kernel.
   :rtype: np.array


.. py:function:: duf_downsample(x, kernel_size=13, scale=4)

   Downsamping with Gaussian kernel used in the DUF official code.

   :param x: Frames to be downsampled, with shape (b, t, c, h, w).
   :type x: Tensor
   :param kernel_size: Kernel size. Default: 13.
   :type kernel_size: int
   :param scale: Downsampling factor. Supported scale: (2, 3, 4).
                 Default: 4.
   :type scale: int

   :returns: DUF downsampled frames.
   :rtype: Tensor