shinestacker 1.1.0__tar.gz → 1.2.1__tar.gz

{shinestacker-1.1.0 → shinestacker-1.2.1}/CHANGELOG.md

@@ -2,12 +2,40 @@
 
 This page reports the main releases only and the main changes therein.
 
+## [v1.2.1] - 2025-09-01
+**Bug fixes and minor improvements**
+* alignment is more tolerant in case of failures: frames are skipped and the running job is not stopped
+* fixed the -x (--expert) option
+* more safety checks prevent crashes for abnormal conditions
+* reference frame index improved with a more consistent treatment, a better numbering scheme and GUI widget 
+* improved project undo action description text
+* some bug fixes and code cleanup
+
+---
+
+## [v1.2.0] - 2025-08-31
+**Parallel processing and more improvements**
+
+* Implemented parallel processing for pyramid stacking algorithm
+* optimized pyramid algorithm: selects automatically the best within the given memory budget to avoid memory issues in case many pictures are selected. Explicit configuration is also possible for specific needs.
+* Implemented automatic subsample option for alignment, balancing and vignetting, now default
+* HLS and HSV corrections now supported for 16 bit images
+* Added luminosity correction in the LAB color space
+* Alignment module skips frames if transformation parameters are out of a reasonable ranges
+* Multilayer modules sends a warning if the estimated output file size is > 1GB
+* "Run all jobs" action is enabled only if more than one job are present
+* Updated default module names in project genereated by "new project" dialog
+* Code refactoring
+* Some GUI fixes
+
+---
+
 ## [v1.1.0] - 2025-08-28
-**New Pyramids algorith, some improvements and more fixes**
+**New Pyramids algorithm, some improvements and more fixes**
 
 ### Changes
 
-* added Pyramids Tiles, that requires less RAM by fusing the image in tiles
+* added Pyramids Tiles, that requires less RAM by fusing images in tiles
 * the alignment module now tolerates images of different shapes
 * noisy pixel mask verifies that the mask has the same shape as input images
 * minor changes to default alignment parameters

{shinestacker-1.1.0/src/shinestacker.egg-info → shinestacker-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shinestacker
-Version: 1.1.0
+Version: 1.2.1
 Summary: ShineStacker
 Author-email: Luca Lista <luka.lista@gmail.com>
 License-Expression: LGPL-3.0

{shinestacker-1.1.0 → shinestacker-1.2.1}/docs/alignment.md

@@ -65,7 +65,7 @@ alignment_config = {
     'border_mode': constants.BORDER_REPLICATE_BLUR,
     'border_value': (0, 0, 0, 0),
     'border_blur': 50,
-    'subsample': 1,
+    'subsample': 0,
     'fast_subsampling': False,
     'min_good_matches': 100
 }
@@ -80,7 +80,7 @@ alignment_config = {
 * ```refine_iters``` (optional, default: 100): refinement iterations. Used only if ```transform=ALIGN_RIGID```.
 * ```align_confidence``` (optional, default: 99.9): alignment algorithm confidence (%). Used only if ```transform=ALIGN_RIGID```. 
 * ```max_iters``` (optional, default: 2000): maximum number of iterations. Used only if ```transform=ALIGN_HOMOGRAPHY```. 
-* ```subsample``` (optional, default: 1): subsample image for faster alignment. Faster, but alignment could be less accurate. It can save time, in particular for large images.
+* ```subsample``` (optional, default: 0=automatic): subsample image for faster alignment. Faster, but alignment could be less accurate if only a small portion of the image is focused. It can save time, in particular for large images.
 * ```fast_subsampling``` (optional, default: ```False```): perform fast image subsampling without interpolation. Used if ```subsample``` is set to ```True```.
 * ```min_good_matches``` (optional, default: 100): if ```subsample```>1 and the number of good matches is below ```min_good_matches```, the alignment is retried without subsampling. This improbes robustness in case a too large subsampling factor is specified. 
 * ```border_mode``` (optional, default: ```BORDER_REPLICATE_BLUR```): border mode. See [Adding borders to your images](https://docs.opencv.org/3.4/dc/da3/tutorial_copyMakeBorder.html) for more details.  Possible values are:

{shinestacker-1.1.0 → shinestacker-1.2.1}/docs/balancing.md

@@ -5,7 +5,12 @@ job.add_action(Actions("balance", [BalanceFrames(*options)])
 ```
   
 Arguments for the constructor of ```BalanceFrames``` are:
-*```channel``` (optional, default: BALANCE_LUMI): channels to be balanced. Possible values are: ```BALANCE_LUMI``` (default): balance equally for R, G and B channels, should be reasonably fine for most of the cases; ```BALANCE_RGB```: balance luminosity separately for R, G and B channels, it may be needed if some but not all of the images have a undesired color dominance; ```BALANCE_HSV```: balance saturation a luminosity value in the HSV (Hue, Saturation, brightness Value) representation, it may be needed in cases of extreme luminosity variation that affects saturation; ```BALANCE_HLS```: balance saturation a luminosity value in the HLS (Hue, Lightness, Saturation) representation, it may be needed in cases of extreme luminosity variation that affects saturation. Note that ```BALANCE_HSV``` and ```BALANCE_HLS``` are only supported for 8-bit images.
+* ```channel``` (optional, default: BALANCE_LUMI): channels to be balanced. Possible values are: 
+   - ```BALANCE_LUMI``` (default): balance equally for R, G and B channels, should be reasonably fine for most of the cases;
+   - ```BALANCE_RGB```: balance luminosity separately for R, G and B channels, it may be needed if some but not all of the images have a undesired color dominance;
+   - ```BALANCE_HSV```: balance saturation and luminosity value in the HSV (Hue, Saturation, brightness Value) color space, it may be needed in cases of extreme luminosity variation that affects saturation;
+   - ```BALANCE_HLS```: balance saturation and luminosity value in the HLS (Hue, Lightness, Saturation) color space, it may be needed in cases of extreme luminosity variation that affects saturation;
+   - ```BALANCE_LAB```: balance luminosity in the LAB color space.
 * ```mask_size``` (optional): if specified, luminosity and color balance is only applied to pixels within a circle of radius equal to the minimum between the image width and height times ```mask_size```, i.e: 0.8 means 80% of a portrait image width or landscape image height. It may beuseful for images with vignetting, in order to avoid including in the balance processing the outer darker pixels.
 * ```intensity_interval``` (optional): if specifies, only pixels with intensity within the specified range are used. It may be useful to remove very dark areas or very light areas. Not used if ```MATCH_HIST``` is specified as value for ```corr_map```. The argument has to be a dictionary where one or both values corresponding to the keys ```min``` and ```max``` can be specified. The default values are:
 ```python
@@ -15,7 +20,7 @@ intensity_interval = {
 }
 ```
 Note that for 8-bit images the maximum intensity is 255, while for 16-bit images the maximum intensity is 65536.
-* ```subsample``` (optional, default: 8): extracts intensity histogram using every n-th pixel in each dimension in order to reduce processing time. By default, it takes one every 8 pixels in horizontal and vertical directions, i.e.: one every 100 pixels in total. This option is not ised if ```corr_map``` is equal to ```BALANCE_MATCH_HIST```.
+* ```subsample``` (optional, default: 0=automatic): extracts intensity histogram using every n-th pixel in each dimension in order to reduce processing time. This option is not ised if ```corr_map``` is equal to ```BALANCE_MATCH_HIST```.
 * ```fast_subsampling``` (optional, default: ```False```): perform fast image subsampling without interpolation. Used if ```subsample``` is set to ```True```.
 * ```corr_map``` (optional, default: ```BALANCE_LINEAR```, possible values: ```BALANCE_LINEAR```, ```BALANCE_GAMMA``` and ```MATCH_HIST```): specifies the type of intensity correction.
    * ```BALANCE_LINEAR```: a linear correction is applied in order to balance the average intensity of the corrected images to the reference image in the specified channels.

{shinestacker-1.1.0 → shinestacker-1.2.1}/docs/focus_stacking.md

@@ -34,7 +34,7 @@ Arguments for the constructor of ```FocusStackBunch``` are:
 
 ## Stack algorithms
 
-```PyramidStack```, Laplacian pyramid focus stacking algorithm, optimized implementation
+```PyramidStack```, Laplacian pyramid focus stacking algorithm
 
 Arguments for the constructor are:
    * ```pyramid_min_size``` (optional, default: 32)
@@ -42,7 +42,20 @@ Arguments for the constructor are:
    * ```gen_kernel``` (optional, default: 0.4)
    * ```float_type``` (optional, default: ```FLOAT_32```, possible values: ```FLOAT_32```, ```FLOAT_64```): precision for internal image representation
 
-```PyramidTilesStack```, Laplacian pyramid with tile pyramid merging to optimize memory usage for large files
+```PyramidTilesStack```, pyramid algorithn with I/O buffered tile pyramid merging to optimize memory usage for large files
+
+Arguments for the constructor are, in addition to the ones for ```PyramidStack```:
+   * ```tile_size``` (optional, default: 512): size of a time
+   * ```n_tiled_layers``` (optional, default: 2): number of layers that are tiled. Usually the last one or two are the ones that take more memory.
+   * ```max_threads``` (optional, default: number of cores, up to a maximum of 8): maximum number of thread used for parallel processing. The actual number of threads does not exceed the number of available cores. 
+
+
+```PyramidAutoStack```, pyramid algorithn with capability to automatically switch from all-in-memory to I/O buffered tiled.
+
+Arguments for the constructor are, in addition to the ones for ```PyramidTilesStack```:
+   * ```mode``` (optional, default: ```auto```): can be ```auto```, ```memory``` or ```tiled```.
+   * ```memory_limit``` (optional, default: 8×1024<sup>3</sup>sup>): memory limit to determine optimal running parameters
+
 
 Arguments for the constructor are the same ad for ```PyramidStack``` plus:
    * ```tile_size``` (optional, default: 512): size of the tile used for partial image merging

{shinestacker-1.1.0 → shinestacker-1.2.1}/docs/job.md

@@ -41,6 +41,6 @@ Arguments for the constructor of ```CombinedActions``` are for the :
 * ```working_path``` (optional): the directory that contains input and output image subdirectories. If not specified, it is the same as ```job.working_path```.
 * ```plot_path``` (optional, default: ```plots```): the directory within ```working_path``` that contains plots produced by the different actions.
 * ```resample``` (optional, default: 1): take every *n*<sup>th</sup> frame in the selected directory. Default: take all frames.
-* ```ref_idx``` (optional): the index of the image used as reference. Images are numbered starting from zero. If not specified, it is the index of the middle image.
+* ```reference_index``` (optional, default: 0): the index of the image used as reference. Images are numbered starting from one to N. -1 is interpreted as the last image, 0 as the median index.
 * ```step_process``` (optional): if equal to ```True``` (default), each image is processed with respect to the previous or next image, depending if its file is placed in alphabetic order after or befor the reference image.
 * ```enabled``` (optional, default: ```True```): allows to switch on and off this module. 

{shinestacker-1.1.0 → shinestacker-1.2.1}/docs/main.md

@@ -103,6 +103,5 @@ pip install ipywidgets
 
 | Issue    |  Workaround    |
 |----------|----------------|
-| Balance modes ```HSV```/```HLS``` don't support 16-bit images | convert to 8-bit or use ```RGB``` or luminosity |
-| PNG support untested  | Convert to TIFF/JPEG first |
-| GUI tests limited     | Report bugs as GitHub issuse |
+| PNG and RAW unsupported  | Convert to TIFF/JPEG first |
+| GUI tests limited     | Report any bugs as GitHub issuse |

{shinestacker-1.1.0 → shinestacker-1.2.1}/docs/vignetting.md

@@ -14,6 +14,7 @@ Arguments for the constructor of ```Vignetting``` are:
 * ```r_steps``` (optional, default: 100): number of radial steps to determine mean pixel luminosity.
 * ```black_threshold``` (optional, default: 1): apply correction only on pixels with luminosity greater than.
 * ```max_correction``` (optional, default: 1): if less than one, the correction is rescaled in order to be at most the specified valye.
+* ```subsample``` (optional, default: 0=automatic): extracts intensity histogram using every n-th pixel in each dimension in order to reduce processing time.
 * ```plot_correction```  (optional, default: ```False```): if ```True```, plot vignetting correction curve for each frame.
 * ```plot_summary```  (optional, default: ```False```): if ```True```, plot a summary histogram with the vignetting correction levels.
 * ```enabled``` (optional, default: ```True```): allows to switch on and off this module.

shinestacker-1.2.1/src/shinestacker/_version.py

@@ -0,0 +1 @@
+__version__ = '1.2.1'

{shinestacker-1.1.0 → shinestacker-1.2.1}/src/shinestacker/algorithms/__init__.py

@@ -8,6 +8,8 @@ from .balance import BalanceFrames
 from .stack import FocusStackBunch, FocusStack
 from .depth_map import DepthMapStack
 from .pyramid import PyramidStack
+from .pyramid_tiles import PyramidTilesStack
+from .pyramid_auto import PyramidAutoStack
 from .multilayer import MultiLayer
 from .noise_detection import NoiseDetection, MaskNoise
 from .vignetting import Vignetting
@@ -16,5 +18,6 @@ logger.addHandler(logging.NullHandler())
 
 __all__ = [
 	'StackJob', 'CombinedActions', 'AlignFrames', 'BalanceFrames', 'FocusStackBunch', 'FocusStack',
-	'DepthMapStack', 'PyramidStack', 'MultiLayer', 'NoiseDetection', 'MaskNoise', 'Vignetting'
+	'DepthMapStack', 'PyramidStack', 'PyramidTilesStack', 'PyramidAutoStack', 'MultiLayer',
+	'NoiseDetection', 'MaskNoise', 'Vignetting'
 ]

{shinestacker-1.1.0 → shinestacker-1.2.1}/src/shinestacker/algorithms/align.py

@@ -1,10 +1,11 @@
-# pylint: disable=C0114, C0115, C0116, E1101, R0914, R0913, R0917, R0912, R0915, R0902
+# pylint: disable=C0114, C0115, C0116, E1101, R0914, R0913, R0917, R0912, R0915, R0902, E1121, W0102
 import logging
+import math
 import numpy as np
 import matplotlib.pyplot as plt
 import cv2
 from .. config.constants import constants
-from .. core.exceptions import AlignmentError, InvalidOptionError
+from .. core.exceptions import InvalidOptionError
 from .. core.colors import color_str
 from .utils import img_8bit, img_bw_8bit, save_plot, img_subsample
 from .stack_framework import SubAction
@@ -29,6 +30,7 @@ _DEFAULT_ALIGNMENT_CONFIG = {
     'refine_iters': constants.DEFAULT_REFINE_ITERS,
     'align_confidence': constants.DEFAULT_ALIGN_CONFIDENCE,
     'max_iters': constants.DEFAULT_ALIGN_MAX_ITERS,
+    'abort_abnormal': constants.DEFAULT_ALIGN_ABORT_ABNORMAL,
     'border_mode': constants.DEFAULT_BORDER_MODE,
     'border_value': constants.DEFAULT_BORDER_VALUE,
     'border_blur': constants.DEFAULT_BORDER_BLUR,
@@ -44,8 +46,91 @@ _cv2_border_mode_map = {
     constants.BORDER_REPLICATE_BLUR: cv2.BORDER_REPLICATE
 }
 
+_AFFINE_THRESHOLDS = {
+    'max_rotation': 10.0,  # degrees
+    'min_scale': 0.9,
+    'max_scale': 1.1,
+    'max_shear': 5.0,  # degrees
+    'max_translation_ratio': 0.1,  # 10% of image dimension
+}
+
+_HOMOGRAPHY_THRESHOLDS = {
+    'max_skew': 10.0,  # degrees
+    'max_scale_change': 1.5,  # max area change ratio
+    'max_aspect_ratio': 2.0,  # max aspect ratio change
+}
+
+
+def decompose_affine_matrix(m):
+    a, b, tx = m[0, 0], m[0, 1], m[0, 2]
+    c, d, ty = m[1, 0], m[1, 1], m[1, 2]
+    scale_x = math.sqrt(a**2 + b**2)
+    scale_y = math.sqrt(c**2 + d**2)
+    rotation = math.degrees(math.atan2(b, a))
+    shear = math.degrees(math.atan2(-c, d)) - rotation
+    shear = (shear + 180) % 360 - 180
+    return (scale_x, scale_y), rotation, shear, (tx, ty)
+
+
+def check_affine_matrix(m, img_shape, affine_thresholds=_AFFINE_THRESHOLDS):
+    if affine_thresholds is None:
+        return True, "No thresholds provided"
+    (scale_x, scale_y), rotation, shear, (tx, ty) = decompose_affine_matrix(m)
+    h, w = img_shape[:2]
+    reasons = []
+    if abs(rotation) > affine_thresholds['max_rotation']:
+        reasons.append(f"rotation too large ({rotation:.1f}°)")
+    if scale_x < affine_thresholds['min_scale'] or scale_x > affine_thresholds['max_scale']:
+        reasons.append(f"x-scale out of range ({scale_x:.2f})")
+    if scale_y < affine_thresholds['min_scale'] or scale_y > affine_thresholds['max_scale']:
+        reasons.append(f"y-scale out of range ({scale_y:.2f})")
+    if abs(shear) > affine_thresholds['max_shear']:
+        reasons.append(f"shear too large ({shear:.1f}°)")
+    max_tx = w * affine_thresholds['max_translation_ratio']
+    max_ty = h * affine_thresholds['max_translation_ratio']
+    if abs(tx) > max_tx:
+        reasons.append(f"x-translation too large (|{tx:.1f}| > {max_tx:.1f})")
+    if abs(ty) > max_ty:
+        reasons.append(f"y-translation too large (|{ty:.1f}| > {max_ty:.1f})")
+    if reasons:
+        return False, "; ".join(reasons)
+    return True, "Transformation within acceptable limits"
 
-def get_good_matches(des_0, des_1, matching_config=None):
+
+def check_homography_distortion(m, img_shape, homography_thresholds=_HOMOGRAPHY_THRESHOLDS):
+    if homography_thresholds is None:
+        return True, "No thresholds provided"
+    h, w = img_shape[:2]
+    corners = np.array([[0, 0], [w, 0], [w, h], [0, h]], dtype=np.float32)
+    transformed = cv2.perspectiveTransform(corners.reshape(1, -1, 2), m).reshape(-1, 2)
+    reasons = []
+    area_orig = w * h
+    area_new = cv2.contourArea(transformed)
+    area_ratio = area_new / area_orig
+    if area_ratio > homography_thresholds['max_scale_change'] or \
+       area_ratio < 1.0 / homography_thresholds['max_scale_change']:
+        reasons.append(f"area change too large ({area_ratio:.2f})")
+    rect = cv2.minAreaRect(transformed.astype(np.float32))
+    (w_rect, h_rect) = rect[1]
+    aspect_ratio = max(w_rect, h_rect) / min(w_rect, h_rect)
+    if aspect_ratio > homography_thresholds['max_aspect_ratio']:
+        reasons.append(f"aspect ratio change too large ({aspect_ratio:.2f})")
+    angles = []
+    for i in range(4):
+        vec1 = transformed[(i + 1) % 4] - transformed[i]
+        vec2 = transformed[(i - 1) % 4] - transformed[i]
+        angle = np.degrees(np.arccos(np.dot(vec1, vec2) /
+                           (np.linalg.norm(vec1) * np.linalg.norm(vec2))))
+        angles.append(angle)
+    max_angle_dev = max(abs(angle - 90) for angle in angles)
+    if max_angle_dev > homography_thresholds['max_skew']:
+        reasons.append(f"angle distortion too large ({max_angle_dev:.1f}°)")
+    if reasons:
+        return False, "; ".join(reasons)
+    return True, "Transformation within acceptable limits"
+
+
+def get_good_matches(des_0, des_ref, matching_config=None):
     matching_config = {**_DEFAULT_MATCHING_CONFIG, **(matching_config or {})}
     match_method = matching_config['match_method']
     good_matches = []
@@ -54,12 +139,12 @@ def get_good_matches(des_0, des_1, matching_config=None):
             {'algorithm': matching_config['flann_idx_kdtree'],
              'trees': matching_config['flann_trees']},
             {'checks': matching_config['flann_checks']})
-        matches = flann.knnMatch(des_0, des_1, k=2)
+        matches = flann.knnMatch(des_0, des_ref, k=2)
         good_matches = [m for m, n in matches
                         if m.distance < matching_config['threshold'] * n.distance]
     elif match_method == constants.MATCHING_NORM_HAMMING:
         bf = cv2.BFMatcher(cv2.NORM_HAMMING, crossCheck=True)
-        good_matches = sorted(bf.match(des_0, des_1), key=lambda x: x.distance)
+        good_matches = sorted(bf.match(des_0, des_ref), key=lambda x: x.distance)
     else:
         raise InvalidOptionError(
             'match_method', match_method,
@@ -87,14 +172,14 @@ def validate_align_config(detector, descriptor, match_method):
                          " require matching method Hamming distance")
 
 
-def detect_and_compute(img_0, img_1, feature_config=None, matching_config=None):
+def detect_and_compute(img_0, img_ref, feature_config=None, matching_config=None):
     feature_config = {**_DEFAULT_FEATURE_CONFIG, **(feature_config or {})}
     matching_config = {**_DEFAULT_MATCHING_CONFIG, **(matching_config or {})}
     feature_config_detector = feature_config['detector']
     feature_config_descriptor = feature_config['descriptor']
     match_method = matching_config['match_method']
     validate_align_config(feature_config_detector, feature_config_descriptor, match_method)
-    img_bw_0, img_bw_1 = img_bw_8bit(img_0), img_bw_8bit(img_1)
+    img_bw_0, img_bw_ref = img_bw_8bit(img_0), img_bw_8bit(img_ref)
     detector_map = {
         constants.DETECTOR_SIFT: cv2.SIFT_create,
         constants.DETECTOR_ORB: cv2.ORB_create,
@@ -114,12 +199,12 @@ def detect_and_compute(img_0, img_1, feature_config=None, matching_config=None):
                                    constants.DETECTOR_AKAZE,
                                    constants.DETECTOR_BRISK):
         kp_0, des_0 = detector.detectAndCompute(img_bw_0, None)
-        kp_1, des_1 = detector.detectAndCompute(img_bw_1, None)
+        kp_ref, des_ref = detector.detectAndCompute(img_bw_ref, None)
     else:
         descriptor = descriptor_map[feature_config_descriptor]()
         kp_0, des_0 = descriptor.compute(img_bw_0, detector.detect(img_bw_0, None))
-        kp_1, des_1 = descriptor.compute(img_bw_1, detector.detect(img_bw_1, None))
-    return kp_0, kp_1, get_good_matches(des_0, des_1, matching_config)
+        kp_ref, des_ref = descriptor.compute(img_bw_ref, detector.detect(img_bw_ref, None))
+    return kp_0, kp_ref, get_good_matches(des_0, des_ref, matching_config)
 
 
 def find_transform(src_pts, dst_pts, transform=constants.DEFAULT_TRANSFORM,
@@ -151,8 +236,10 @@ def find_transform(src_pts, dst_pts, transform=constants.DEFAULT_TRANSFORM,
     return result
 
 
-def align_images(img_1, img_0, feature_config=None, matching_config=None, alignment_config=None,
-                 plot_path=None, callbacks=None):
+def align_images(img_ref, img_0, feature_config=None, matching_config=None, alignment_config=None,
+                 plot_path=None, callbacks=None,
+                 affine_thresholds=_AFFINE_THRESHOLDS,
+                 homography_thresholds=_HOMOGRAPHY_THRESHOLDS):
     feature_config = {**_DEFAULT_FEATURE_CONFIG, **(feature_config or {})}
     matching_config = {**_DEFAULT_MATCHING_CONFIG, **(matching_config or {})}
     alignment_config = {**_DEFAULT_ALIGNMENT_CONFIG, **(alignment_config or {})}
@@ -163,19 +250,23 @@ def align_images(img_1, img_0, feature_config=None, matching_config=None, alignm
     min_matches = 4 if alignment_config['transform'] == constants.ALIGN_HOMOGRAPHY else 3
     if callbacks and 'message' in callbacks:
         callbacks['message']()
-    h_ref, w_ref = img_1.shape[:2]
+    h_ref, w_ref = img_ref.shape[:2]
     h0, w0 = img_0.shape[:2]
     subsample = alignment_config['subsample']
+    if subsample == 0:
+        img_res = (float(h0) / constants.ONE_KILO) * (float(w0) / constants.ONE_KILO)
+        target_res = constants.DEFAULT_ALIGN_RES_TARGET_MPX
+        subsample = int(1 + math.floor(img_res / target_res))
     fast_subsampling = alignment_config['fast_subsampling']
     min_good_matches = alignment_config['min_good_matches']
     while True:
         if subsample > 1:
             img_0_sub = img_subsample(img_0, subsample, fast_subsampling)
-            img_1_sub = img_subsample(img_1, subsample, fast_subsampling)
+            img_ref_sub = img_subsample(img_ref, subsample, fast_subsampling)
         else:
-            img_0_sub, img_1_sub = img_0, img_1
-        kp_0, kp_1, good_matches = detect_and_compute(img_0_sub, img_1_sub,
-                                                      feature_config, matching_config)
+            img_0_sub, img_ref_sub = img_0, img_ref
+        kp_0, kp_ref, good_matches = detect_and_compute(img_0_sub, img_ref_sub,
+                                                        feature_config, matching_config)
         n_good_matches = len(good_matches)
         if n_good_matches > min_good_matches or subsample == 1:
             break
@@ -191,7 +282,7 @@ def align_images(img_1, img_0, feature_config=None, matching_config=None, alignm
     if n_good_matches >= min_matches:
         transform = alignment_config['transform']
         src_pts = np.float32([kp_0[m.queryIdx].pt for m in good_matches]).reshape(-1, 1, 2)
-        dst_pts = np.float32([kp_1[m.trainIdx].pt for m in good_matches]).reshape(-1, 1, 2)
+        dst_pts = np.float32([kp_ref[m.trainIdx].pt for m in good_matches]).reshape(-1, 1, 2)
         m, msk = find_transform(src_pts, dst_pts, transform, alignment_config['align_method'],
                                 *(alignment_config[k]
                                   for k in ['rans_threshold', 'max_iters',
@@ -199,11 +290,11 @@ def align_images(img_1, img_0, feature_config=None, matching_config=None, alignm
         if plot_path is not None:
             matches_mask = msk.ravel().tolist()
             img_match = cv2.cvtColor(cv2.drawMatches(
-                img_8bit(img_0_sub), kp_0, img_8bit(img_1_sub),
-                kp_1, good_matches, None, matchColor=(0, 255, 0),
+                img_8bit(img_0_sub), kp_0, img_8bit(img_ref_sub),
+                kp_ref, good_matches, None, matchColor=(0, 255, 0),
                 singlePointColor=None, matchesMask=matches_mask,
                 flags=2), cv2.COLOR_BGR2RGB)
-            plt.figure(figsize=(10, 5))
+            plt.figure(figsize=constants.PLT_FIG_SIZE)
             plt.imshow(img_match, 'gray')
             save_plot(plot_path)
             if callbacks and 'save_plot' in callbacks:
@@ -225,6 +316,20 @@ def align_images(img_1, img_0, feature_config=None, matching_config=None, alignm
                 m[:, 2] = translation_fullres
             else:
                 raise InvalidOptionError("transform", transform)
+
+        transform_type = alignment_config['transform']
+        is_valid = True
+        reason = ""
+        if transform_type == constants.ALIGN_RIGID:
+            is_valid, reason = check_affine_matrix(
+                m, img_0.shape, affine_thresholds)
+        elif transform_type == constants.ALIGN_HOMOGRAPHY:
+            is_valid, reason = check_homography_distortion(
+                m, img_0.shape, homography_thresholds)
+        if not is_valid:
+            if callbacks and 'warning' in callbacks:
+                callbacks['warning'](f"invalid transformation: {reason}")
+            return n_good_matches, None, None
         if callbacks and 'align_message' in callbacks:
             callbacks['align_message']()
         img_mask = np.ones_like(img_0, dtype=np.uint8)
@@ -284,7 +389,7 @@ class AlignFrames(SubAction):
     def sub_msg(self, msg, color=constants.LOG_COLOR_LEVEL_3):
         self.process.sub_message_r(color_str(msg, color))
 
-    def align_images(self, idx, img_1, img_0):
+    def align_images(self, idx, img_ref, img_0):
         idx_str = f"{idx:04d}"
         callbacks = {
             'message': lambda: self.sub_msg(': find matches'),
@@ -303,37 +408,47 @@ class AlignFrames(SubAction):
                 f"{self.process.name}-matches-{idx_str}.pdf"
         else:
             plot_path = None
+        if self.alignment_config['abort_abnormal']:
+            affine_thresholds = _AFFINE_THRESHOLDS
+            homography_thresholds = _HOMOGRAPHY_THRESHOLDS
+        else:
+            affine_thresholds = None
+            homography_thresholds = None
         n_good_matches, _m, img = align_images(
-            img_1, img_0,
+            img_ref, img_0,
             feature_config=self.feature_config,
             matching_config=self.matching_config,
             alignment_config=self.alignment_config,
             plot_path=plot_path,
-            callbacks=callbacks
+            callbacks=callbacks,
+            affine_thresholds=affine_thresholds,
+            homography_thresholds=homography_thresholds
         )
         self.n_matches[idx] = n_good_matches
         if n_good_matches < self.min_matches:
-            self.process.sub_message(f": image not aligned, too few matches found: "
-                                     f"{n_good_matches}", level=logging.CRITICAL)
-            raise AlignmentError(idx, f"Image not aligned, too few matches found: "
-                                 f"{n_good_matches} < {self.min_matches}")
+            self.process.sub_message(color_str(f": image not aligned, too few matches found: "
+                                     f"{n_good_matches}", constants.LOG_COLOR_WARNING),
+                                     level=logging.WARNING)
+            return None
         return img
 
     def begin(self, process):
         self.process = process
-        self.n_matches = np.zeros(process.counts)
+        self.n_matches = np.zeros(process.total_action_counts)
 
     def end(self):
         if self.plot_summary:
-            plt.figure(figsize=(10, 5))
+            plt.figure(figsize=constants.PLT_FIG_SIZE)
             x = np.arange(1, len(self.n_matches) + 1, dtype=int)
             no_ref = x != self.process.ref_idx + 1
             x = x[no_ref]
             y = self.n_matches[no_ref]
-            y_max = y[1] \
-                if self.process.ref_idx == 0 \
-                else y[-1] if self.process.ref_idx == len(y) - 1 \
-                else (y[self.process.ref_idx - 1] + y[self.process.ref_idx]) / 2
+            if self.process.ref_idx == 0:
+                y_max = y[1]
+            elif self.process.ref_idx >= len(y):
+                y_max = y[-1]
+            else:
+                y_max = (y[self.process.ref_idx - 1] + y[self.process.ref_idx]) / 2
 
             plt.plot([self.process.ref_idx + 1, self.process.ref_idx + 1],
                      [0, y_max], color='cornflowerblue', linestyle='--', label='reference frame')