shinestacker 0.2.0.post1.dev1__py3-none-any.whl

shinestacker/algorithms/pyramid.py

@@ -0,0 +1,176 @@
+import numpy as np
+import cv2
+from .. config.constants import constants
+from .. core.colors import color_str
+from .. core.exceptions import RunStopException, ImageLoadError, InvalidOptionError
+from .utils import read_img, get_img_metadata, validate_image
+
+
+class PyramidBase:
+    def __init__(self, min_size=constants.DEFAULT_PY_MIN_SIZE, kernel_size=constants.DEFAULT_PY_KERNEL_SIZE,
+                 gen_kernel=constants.DEFAULT_PY_GEN_KERNEL, float_type=constants.DEFAULT_PY_FLOAT):
+        self.min_size = min_size
+        self.kernel_size = kernel_size
+        self.pad_amount = (kernel_size - 1) // 2
+        self.do_step_callback = False
+        kernel = np.array([0.25 - gen_kernel / 2.0, 0.25, gen_kernel, 0.25, 0.25 - gen_kernel / 2.0])
+        self.gen_kernel = np.outer(kernel, kernel)
+        if float_type == constants.FLOAT_32:
+            self.float_type = np.float32
+        elif float_type == constants.FLOAT_64:
+            self.float_type = np.float64
+        else:
+            raise InvalidOptionError("float_type", float_type, details=" valid values are FLOAT_32 and FLOAT_64")
+
+    def print_message(self, msg):
+        self.process.sub_message_r(color_str(msg, "light_blue"))
+
+    def steps_per_frame(self):
+        return 1
+
+    def convolve(self, image):
+        return cv2.filter2D(image, -1, self.gen_kernel, borderType=cv2.BORDER_REFLECT101)
+
+    def reduce_layer(self, layer):
+        if len(layer.shape) == 2:
+            return self.convolve(layer)[::2, ::2]
+        reduced_channels = [self.reduce_layer(layer[:, :, channel]) for channel in range(layer.shape[2])]
+        return np.stack(reduced_channels, axis=-1)
+
+    def expand_layer(self, layer):
+        if len(layer.shape) == 2:
+            expand = np.empty((2 * layer.shape[0], 2 * layer.shape[1]), dtype=layer.dtype)
+            expand[::2, ::2] = layer
+            expand[1::2, :] = 0
+            expand[:, 1::2] = 0
+            return 4. * self.convolve(expand)
+        ch_layer = self.expand_layer(layer[:, :, 0])
+        next_layer = np.zeros(list(ch_layer.shape) + [layer.shape[2]], dtype=layer.dtype)
+        next_layer[:, :, 0] = ch_layer
+        for channel in range(1, layer.shape[2]):
+            next_layer[:, :, channel] = self.expand_layer(layer[:, :, channel])
+        return next_layer
+
+    def fuse_laplacian(self, laplacians):
+        gray_laps = [cv2.cvtColor(lap.astype(np.float32), cv2.COLOR_BGR2GRAY) for lap in laplacians]
+        energies = [self.convolve(np.square(gray_lap)) for gray_lap in gray_laps]
+        best = np.argmax(energies, axis=0)
+        fused = np.zeros_like(laplacians[0])
+        for i, lap in enumerate(laplacians):
+            fused += np.where(best[:, :, np.newaxis] == i, lap, 0)
+        return fused
+
+    def collapse(self, pyramid):
+        img = pyramid[-1]
+        for layer in pyramid[-2::-1]:
+            expanded = self.expand_layer(img)
+            if expanded.shape != layer.shape:
+                expanded = expanded[:layer.shape[0], :layer.shape[1]]
+            img = expanded + layer
+        return np.clip(np.abs(img), 0, self.max_pixel_value)
+
+    def entropy(self, image):
+        levels, counts = np.unique(image.astype(self.dtype), return_counts=True)
+        probabilities = np.zeros((self.num_pixel_values), dtype=self.float_type)
+        probabilities[levels] = counts.astype(self.float_type) / counts.sum()
+        padded_image = cv2.copyMakeBorder(image, self.pad_amount, self.pad_amount, self.pad_amount,
+                                          self.pad_amount, cv2.BORDER_REFLECT101)
+        return np.fromfunction(np.vectorize(lambda row, column: self.area_entropy(
+            self.get_pad(padded_image, row, column), probabilities)), image.shape[:2], dtype=int)
+
+    def area_entropy(self, area, probabilities):
+        levels = area.flatten()
+        return self.float_type(-1. * (levels * np.log(probabilities[levels])).sum())
+
+    def get_pad(self, padded_image, row, column):
+        return padded_image[row + self.pad_amount + self.offset[:, np.newaxis], column + self.pad_amount + self.offset]
+
+    def area_deviation(self, area):
+        return np.square(area - np.average(area).astype(self.float_type)).sum() / area.size
+
+    def deviation(self, image):
+        padded_image = cv2.copyMakeBorder(image, self.pad_amount, self.pad_amount, self.pad_amount,
+                                          self.pad_amount, cv2.BORDER_REFLECT101)
+        return np.fromfunction(
+            np.vectorize(lambda row, column: self.area_deviation(self.get_pad(padded_image, row, column))),
+            image.shape[:2], dtype=int)
+
+    def get_fused_base(self, images):
+        layers, height, width, _ = images.shape
+        entropies = np.zeros(images.shape[:3], dtype=self.float_type)
+        deviations = np.copy(entropies)
+        gray_images = np.array([cv2.cvtColor(images[layer].astype(np.float32),
+                                             cv2.COLOR_BGR2GRAY).astype(self.dtype) for layer in range(layers)])
+        entropies = np.array([self.entropy(img) for img in gray_images])
+        deviations = np.array([self.deviation(img) for img in gray_images])
+        best_e = np.argmax(entropies, axis=0)
+        best_d = np.argmax(deviations, axis=0)
+        fused = np.zeros(images.shape[1:], dtype=self.float_type)
+        for layer in range(layers):
+            img = images[layer]
+            fused += np.where(best_e[:, :, np.newaxis] == layer, img, 0)
+            fused += np.where(best_d[:, :, np.newaxis] == layer, img, 0)
+        return (fused / 2).astype(images.dtype)
+
+
+class PyramidStack(PyramidBase):
+    def __init__(self, min_size=constants.DEFAULT_PY_MIN_SIZE, kernel_size=constants.DEFAULT_PY_KERNEL_SIZE,
+                 gen_kernel=constants.DEFAULT_PY_GEN_KERNEL, float_type=constants.DEFAULT_PY_FLOAT):
+        super().__init__(min_size, kernel_size, gen_kernel, float_type)
+        self.offset = np.arange(-self.pad_amount, self.pad_amount + 1)
+
+    def name(self):
+        return "pyramid"
+
+    def process_single_image(self, img, levels):
+        pyramid = [img.astype(self.float_type)]
+        for _ in range(levels):
+            next_layer = self.reduce_layer(pyramid[-1])
+            if min(next_layer.shape[:2]) < 4:
+                break
+            pyramid.append(next_layer)
+        laplacian = [pyramid[-1]]
+        for level in range(len(pyramid) - 1, 0, -1):
+            expanded = self.expand_layer(pyramid[level])
+            pyr = pyramid[level - 1]
+            h, w = pyr.shape[:2]
+            expanded = expanded[:h, :w]
+            laplacian.append(pyr - expanded)
+        return laplacian[::-1]
+
+    def fuse_pyramids(self, all_laplacians):
+        fused = [self.get_fused_base(np.stack([p[-1] for p in all_laplacians], axis=0))]
+        for layer in range(len(all_laplacians[0]) - 2, -1, -1):
+            self.print_message(': fusing pyramids, layer: {}'.format(layer + 1))
+            laplacians = np.stack([p[layer] for p in all_laplacians], axis=0)
+            fused.append(self.fuse_laplacian(laplacians))
+        self.print_message(': pyramids fusion completed')
+        return fused[::-1]
+
+    def focus_stack(self, filenames):
+        metadata = None
+        all_laplacians = []
+        levels = None
+        for i, img_path in enumerate(filenames):
+            self.print_message(': validating file {}'.format(img_path.split('/')[-1]))
+            img = read_img(img_path)
+            if img is None:
+                raise ImageLoadError(img_path)
+            if metadata is None:
+                metadata = get_img_metadata(img)
+                self.dtype = metadata[1]
+                self.num_pixel_values = constants.NUM_UINT8 if self.dtype == np.uint8 else constants.NUM_UINT16
+                self.max_pixel_value = constants.MAX_UINT8 if self.dtype == np.uint8 else constants.MAX_UINT16
+                levels = int(np.log2(min(img.shape[:2]) / self.min_size))
+            else:
+                validate_image(img, *metadata)
+            if self.do_step_callback:
+                self.process.callback('after_step', self.process.id, self.process.name, i)
+            if self.process.callback('check_running', self.process.id, self.process.name) is False:
+                raise RunStopException(self.name)
+        for img_path in filenames:
+            self.print_message(': processing file {}'.format(img_path.split('/')[-1]))
+            img = read_img(img_path)
+            all_laplacians.append(self.process_single_image(img, levels))
+        stacked_image = self.collapse(self.fuse_pyramids(all_laplacians))
+        return stacked_image.astype(self.dtype)

shinestacker/algorithms/stack.py

@@ -0,0 +1,112 @@
+import numpy as np
+import cv2
+import os
+from .. config.constants import constants
+from .. core.colors import color_str
+from .. core.framework import JobBase
+from .. core.exceptions import InvalidOptionError
+from .utils import write_img
+from .stack_framework import FrameDirectory, ActionList
+from .exif import copy_exif_from_file_to_file
+
+
+class FocusStackBase:
+    def __init__(self, stack_algo, exif_path='',
+                 prefix=constants.DEFAULT_STACK_PREFIX,
+                 denoise=0, plot_stack=False):
+        self.stack_algo = stack_algo
+        self.exif_path = exif_path
+        self.prefix = prefix if prefix != '' else constants.DEFAULT_STACK_PREFIX
+        self.denoise = denoise
+        self.plot_stack = plot_stack
+        self.stack_algo.process = self
+        self.frame_count = -1
+
+    def focus_stack(self, filenames):
+        self.sub_message_r(': reading input files')
+        img_files = sorted([os.path.join(self.input_full_path, name) for name in filenames])
+        stacked_img = self.stack_algo.focus_stack(img_files)
+        in_filename = filenames[0].split(".")
+        out_filename = f"{self.output_dir}/{self.prefix}{in_filename[0]}." + '.'.join(in_filename[1:])
+        if self.denoise > 0:
+            self.sub_message_r(': denoise image')
+            stacked_img = cv2.fastNlMeansDenoisingColored(stacked_img, None, self.denoise, self.denoise, 7, 21)
+        write_img(out_filename, stacked_img)
+        if self.exif_path != '' and stacked_img.dtype == np.uint8:
+            self.sub_message_r(': copy exif data')
+            dirpath, _, fnames = next(os.walk(self.exif_path))
+            fnames = [name for name in fnames if os.path.splitext(name)[-1][1:].lower() in constants.EXTENSIONS]
+            exif_filename = f"{self.exif_path}/{fnames[0]}"
+            copy_exif_from_file_to_file(exif_filename, out_filename)
+            self.sub_message_r(' ' * 60)
+        if self.plot_stack:
+            idx_str = "{:04d}".format(self.frame_count) if self.frame_count >= 0 else ''
+            name = f"{self.name}: {self.stack_algo.name()}"
+            if idx_str != '':
+                name += f"\nbunch: {idx_str}"
+            self.callback('save_plot', self.id, name, out_filename)
+        if self.frame_count >= 0:
+            self.frame_count += 1
+
+    def init(self, job, working_path):
+        if self.exif_path is None:
+            self.exif_path = job.paths[0]
+        if self.exif_path != '':
+            self.exif_path = working_path + "/" + self.exif_path
+
+
+class FocusStackBunch(FocusStackBase, FrameDirectory, ActionList):
+    def __init__(self, name, stack_algo, enabled=True, **kwargs):
+        FocusStackBase.__init__(self, stack_algo,
+                                exif_path=kwargs.pop('exif_path', ''),
+                                prefix=kwargs.pop('prefix', constants.DEFAULT_STACK_PREFIX),
+                                denoise=kwargs.pop('denoise', 0),
+                                plot_stack=kwargs.pop('plot_stack', constants.DEFAULT_PLOT_STACK_BUNCH))
+        FrameDirectory.__init__(self, name, **kwargs)
+        ActionList.__init__(self, name, enabled)
+        self.frame_count = 0
+        self.frames = kwargs.get('frames', constants.DEFAULT_FRAMES)
+        self.overlap = kwargs.get('overlap', constants.DEFAULT_OVERLAP)
+        self.denoise = kwargs.get('denoise', 0)
+        self.stack_algo.do_step_callback = False
+        if self.overlap >= self.frames:
+            raise InvalidOptionError("overlap", self.overlap, "overlap must be smaller than batch size")
+
+    def init(self, job):
+        FrameDirectory.init(self, job)
+        FocusStackBase.init(self, job, self.working_path)
+
+    def begin(self):
+        ActionList.begin(self)
+        fnames = self.folder_filelist(self.input_full_path)
+        self.__chunks = [fnames[x:x + self.frames] for x in range(0, len(fnames) - self.overlap, self.frames - self.overlap)]
+        self.set_counts(len(self.__chunks))
+
+    def end(self):
+        ActionList.end(self)
+
+    def run_step(self):
+        self.print_message_r(color_str("fusing bunch: {}".format(self.count), "blue"))
+        self.focus_stack(self.__chunks[self.count - 1])
+        self.callback('after_step', self.id, self.name, self.count)
+
+
+class FocusStack(FocusStackBase, FrameDirectory, JobBase):
+    def __init__(self, name, stack_algo, enabled=True, **kwargs):
+        FocusStackBase.__init__(self, stack_algo,
+                                exif_path=kwargs.pop('exif_path', ''),
+                                prefix=kwargs.pop('prefix', constants.DEFAULT_STACK_PREFIX),
+                                denoise=kwargs.pop('denoise', 0),
+                                plot_stack=kwargs.pop('plot_stack', constants.DEFAULT_PLOT_STACK))
+        FrameDirectory.__init__(self, name, **kwargs)
+        JobBase.__init__(self, name, enabled)
+        self.stack_algo.do_step_callback = True
+
+    def run_core(self):
+        self.set_filelist()
+        self.callback('step_counts', self.id, self.name, self.stack_algo.steps_per_frame() * len(self.filenames))
+        self.focus_stack(self.filenames)
+
+    def init(self, job):
+        FrameDirectory.init(self, job)
+        FocusStackBase.init(self, job, self.working_path)

shinestacker/algorithms/stack_framework.py

@@ -0,0 +1,248 @@
+import logging
+import os
+from .. config.constants import constants
+from .. core.colors import color_str
+from .. core.framework import Job, ActionList
+from .. core.core_utils import check_path_exists
+from .. core.exceptions import ShapeError, BitDepthError, RunStopException
+from .utils import read_img, write_img
+
+
+class StackJob(Job):
+    def __init__(self, name, working_path, input_path='', **kwargs):
+        check_path_exists(working_path)
+        self.working_path = working_path
+        if input_path == '':
+            self.paths = []
+        else:
+            self.paths = [input_path]
+        Job.__init__(self, name, **kwargs)
+
+    def init(self, a):
+        a.init(self)
+
+
+class FramePaths:
+    def __init__(self, name, input_path='', output_path='', working_path='', plot_path=constants.DEFAULT_PLOTS_PATH,
+                 scratch_output_dir=True, resample=1, reverse_order=constants.DEFAULT_FILE_REVERSE_ORDER, **kwargs):
+        self.name = name
+        self.working_path = working_path
+        self.plot_path = plot_path
+        self.input_path = input_path
+        self.output_path = output_path
+        self.resample = resample
+        self.reverse_order = reverse_order
+        self.scratch_output_dir = scratch_output_dir
+
+    def set_filelist(self):
+        self.filenames = self.folder_filelist(self.input_full_path)
+        file_list = self.input_full_path.replace(self.working_path, '').lstrip('/')
+        self.print_message(color_str(": {} files ".format(len(self.filenames)) + "in folder: " + file_list, 'blue'))
+        self.print_message(color_str("focus stacking", 'blue'))
+
+    def init(self, job):
+        if self.working_path == '':
+            self.working_path = job.working_path
+        check_path_exists(self.working_path)
+        if self.output_path == '':
+            self.output_path = self.name
+        self.output_dir = self.working_path + ('' if self.working_path[-1] == '/' else '/') + self.output_path
+        if not os.path.exists(self.output_dir):
+            os.makedirs(self.output_dir)
+        else:
+            list_dir = os.listdir(self.output_dir)
+            if len(list_dir) > 0:
+                if self.scratch_output_dir:
+                    if self.enabled:
+                        for filename in list_dir:
+                            file_path = os.path.join(self.output_dir, filename)
+                            if os.path.isfile(file_path):
+                                os.remove(file_path)
+                        self.print_message(color_str(f": output directory {self.output_path} content erased", 'yellow'))
+                    else:
+                        self.print_message(color_str(f": module disabled, output directory {self.output_path} not scratched", 'yellow'))
+                else:
+                    self.print_message(color_str(f": output directory {self.output_path} not empty, "
+                        "files may be overwritten or merged with existing ones.", 'yellow'), level=logging.WARNING) # noqa
+        if self.plot_path == '':
+            self.plot_path = self.working_path + ('' if self.working_path[-1] == '/' else '/') + self.plot_path
+            if not os.path.exists(self.plot_path):
+                os.makedirs(self.plot_path)
+        if self.input_path == '':
+            if len(job.paths) == 0:
+                raise Exception(f"Job {job.name} does not have any configured path")
+            self.input_path = job.paths[-1]
+        job.paths.append(self.output_path)
+
+
+class FrameDirectory(FramePaths):
+    def __init__(self, name, **kwargs):
+        FramePaths.__init__(self, name, **kwargs)
+
+    def folder_list_str(self):
+        if isinstance(self.input_full_path, list):
+            file_list = ", ".join([i for i in self.input_full_path.replace(self.working_path, '').lstrip('/')])
+            return "folder{}: ".format('s' if len(self.input_full_path) > 1 else '') + file_list
+        else:
+            return "folder: " + self.input_full_path.replace(self.working_path, '').lstrip('/')
+
+    def folder_filelist(self, path):
+        src_contents = os.walk(self.input_full_path)
+        dirpath, _, filenames = next(src_contents)
+        filelist = [name for name in filenames if os.path.splitext(name)[-1][1:].lower() in constants.EXTENSIONS]
+        filelist.sort()
+        if self.reverse_order:
+            filelist.reverse()
+        if self.resample > 1:
+            filelist = filelist[0::self.resample]
+        return filelist
+
+    def init(self, job):
+        FramePaths.init(self, job)
+        self.input_full_path = self.working_path + ('' if self.working_path[-1] == '/' else '/') + self.input_path
+        check_path_exists(self.input_full_path)
+        job.paths.append(self.output_path)
+
+
+class FrameMultiDirectory:
+    def __init__(self, name, input_path='', output_path='', working_path='', plot_path=constants.DEFAULT_PLOTS_PATH,
+                 scratch_output_dir=True, resample=1, reverse_order=constants.DEFAULT_FILE_REVERSE_ORDER, **kwargs):
+        FramePaths.__init__(self, name, input_path, output_path, working_path, plot_path, scratch_output_dir, resample, reverse_order, **kwargs)
+
+    def folder_list_str(self):
+        if isinstance(self.input_full_path, list):
+            file_list = ", ".join([d.replace(self.working_path, '').lstrip('/') for d in self.input_full_path])
+            return "folder{}: ".format('s' if len(self.input_full_path) > 1 else '') + file_list
+        else:
+            return "folder: " + self.input_full_path.replace(self.working_path, '').lstrip('/')
+
+    def folder_filelist(self):
+        if isinstance(self.input_full_path, str):
+            dirs = [self.input_full_path]
+            paths = [self.input_path]
+        elif hasattr(self.input_full_path, "__len__"):
+            dirs = self.input_full_path
+            paths = self.input_path
+        else:
+            raise Exception("input_full_path option must contain a path or an array of paths")
+        files = []
+        for d, p in zip(dirs, paths):
+            filelist = []
+            for dirpath, _, filenames in os.walk(d):
+                filelist = [p + "/" + name for name in filenames if os.path.splitext(name)[-1][1:].lower() in constants.EXTENSIONS]
+                if self.reverse_order:
+                    filelist.reverse()
+                if self.resample > 1:
+                    filelist = filelist[0::self.resample]
+                files += filelist
+            if len(files) == 0:
+                self.print_message(color_str(f"input folder {p} does not contain any image", "red"), level=logging.WARNING)
+        return files
+
+    def init(self, job):
+        FramePaths.init(self, job)
+        if isinstance(self.input_path, str):
+            self.input_full_path = self.working_path + ('' if self.working_path[-1] == '/' else '/') + self.input_path
+            check_path_exists(self.input_full_path)
+        elif hasattr(self.input_path, "__len__"):
+            self.input_full_path = []
+            for path in self.input_path:
+                self.input_full_path.append(self.working_path + ('' if self.working_path[-1] == '/' else '/') + path)
+        job.paths.append(self.output_path)
+
+
+class FramesRefActions(FrameDirectory, ActionList):
+    def __init__(self, name, enabled=True, ref_idx=-1, step_process=False, **kwargs):
+        FrameDirectory.__init__(self, name, **kwargs)
+        ActionList.__init__(self, name, enabled)
+        self.ref_idx = ref_idx
+        self.step_process = step_process
+
+    def begin(self):
+        ActionList.begin(self)
+        self.set_filelist()
+        self.set_counts(len(self.filenames))
+        if self.ref_idx == -1:
+            self.ref_idx = len(self.filenames) // 2
+
+    def end(self):
+        ActionList.end(self)
+
+    def run_frame(self, idx, ref_idx):
+        assert False, 'abstract method'
+
+    def run_step(self):
+        if self.count == 1:
+            self.__idx = self.ref_idx if self.step_process else 0
+            self.__ref_idx = self.ref_idx
+            self.__idx_step = +1
+        ll = len(self.filenames)
+        self.print_message_r(
+            color_str("step {}/{}: process file: {}, reference: {}".format(self.count, ll, self.filenames[self.__idx],
+                                                                           self.filenames[self.__ref_idx]), "blue"))
+        self.run_frame(self.__idx, self.__ref_idx)
+        if self.__idx < ll:
+            if self.step_process:
+                self.__ref_idx = self.__idx
+            self.__idx += self.__idx_step
+        if self.__idx == ll:
+            self.__idx = self.ref_idx - 1
+            if self.step_process:
+                self.__ref_idx = self.ref_idx
+            self.__idx_step = -1
+
+
+class SubAction:
+    def __init__(self, enabled=True):
+        self.enabled = enabled
+
+
+class CombinedActions(FramesRefActions):
+    def __init__(self, name, actions=[], enabled=True, **kwargs):
+        FramesRefActions.__init__(self, name, enabled, **kwargs)
+        self.__actions = actions
+
+    def begin(self):
+        FramesRefActions.begin(self)
+        for a in self.__actions:
+            if a.enabled:
+                a.begin(self)
+
+    def img_ref(self, idx):
+        filename = self.filenames[idx]
+        img = read_img((self.output_dir if self.step_process else self.input_full_path) + "/" + filename)
+        self.dtype = img.dtype
+        self.shape = img.shape
+        if img is None:
+            raise Exception("Invalid file: " + self.input_full_path + "/" + filename)
+        return img
+
+    def run_frame(self, idx, ref_idx):
+        filename = self.filenames[idx]
+        self.sub_message_r(': read input image')
+        img = read_img(self.input_full_path + "/" + filename)
+        if hasattr(self, 'dtype') and img.dtype != self.dtype:
+            raise BitDepthError(img.dtype, self.dtype)
+        if hasattr(self, 'shape') and img.shape != self.shape:
+            raise ShapeError(img.shape, self.shape)
+        if img is None:
+            raise Exception("Invalid file: " + self.input_full_path + "/" + filename)
+        if len(self.__actions) == 0:
+            self.sub_message(color_str(": no actions specified.", "red"), level=logging.WARNING)
+        for a in self.__actions:
+            if not a.enabled:
+                self.get_logger().warning(color_str(self.base_message + ": sub-action disabled", 'red'))
+            else:
+                if self.callback('check_running', self.id, self.name) is False:
+                    raise RunStopException(self.name)
+                img = a.run_frame(idx, ref_idx, img)
+        self.sub_message_r(': write output image')
+        if img is not None:
+            write_img(self.output_dir + "/" + filename, img)
+        else:
+            self.print_message("No output file resulted from processing input file: " + self.input_full_path + "/" + filename, level=logging.WARNING)
+
+    def end(self):
+        for a in self.__actions:
+            if a.enabled:
+                a.end()

shinestacker/algorithms/utils.py

@@ -0,0 +1,71 @@
+import cv2
+import os
+import numpy as np
+import logging
+import matplotlib.pyplot as plt
+from .. config.config import config
+from .. core.exceptions import ShapeError, BitDepthError
+
+
+def read_img(file_path):
+    if not os.path.isfile(file_path):
+        raise Exception("File does not exist: " + file_path)
+    ext = file_path.split(".")[-1]
+    if ext == 'jpeg' or ext == 'jpg':
+        img = cv2.imread(file_path)
+    elif ext == 'tiff' or ext == 'tif' or ext == 'png':
+        img = cv2.imread(file_path, cv2.IMREAD_UNCHANGED)
+    return img
+
+
+def write_img(file_path, img):
+    ext = file_path.split(".")[-1]
+    if ext == 'jpeg' or ext == 'jpg':
+        cv2.imwrite(file_path, img, [int(cv2.IMWRITE_JPEG_QUALITY), 100])
+    elif ext == 'tiff' or ext == 'tif':
+        cv2.imwrite(file_path, img, [int(cv2.IMWRITE_TIFF_COMPRESSION), 1])
+    elif ext == 'png':
+        cv2.imwrite(file_path, img)
+
+
+def img_8bit(img):
+    return (img >> 8).astype('uint8') if img.dtype == np.uint16 else img
+
+
+def img_bw_8bit(img):
+    img = img_8bit(img)
+    if len(img.shape) == 3:
+        return cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+    elif len(img.shape) == 2:
+        return img
+    else:
+        raise ValueError(f"Unsupported image format: {img.shape}")
+
+
+def img_bw(img):
+    return cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+
+
+def get_img_metadata(img):
+    return img.shape[:2], img.dtype
+
+
+def validate_image(img, expected_shape=None, expected_dtype=None):
+    shape, dtype = get_img_metadata(img)
+    if expected_shape and shape[:2] != expected_shape[:2]:
+        raise ShapeError(expected_shape, shape)
+    if expected_dtype and dtype != expected_dtype:
+        raise BitDepthError(expected_dtype, dtype)
+
+
+def save_plot(filename):
+    logging.getLogger(__name__).debug("save plot file: " + filename)
+    dir_path = os.path.dirname(filename)
+    if not dir_path:
+        dir_path = '.'
+    if not os.path.isdir(dir_path):
+        os.makedirs(dir_path)
+    plt.savefig(filename, dpi=150)
+    if config.JUPYTER_NOTEBOOK:
+        plt.show()
+    plt.close('all')