shinestacker 0.2.0.post1.dev1__tar.gz

shinestacker-0.2.0.post1.dev1/.flake8

@@ -0,0 +1,4 @@
+[flake8]
+exclude = */.ipynb_checkpoints/*,src/focusstack/_version.py
+max-line-length = 160
+ignore = E402

shinestacker-0.2.0.post1.dev1/.github/workflows/ci-multiplatform.yml

@@ -0,0 +1,39 @@
+---
+
+name: CI multiplatform
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    permissions:
+      contents: read
+      pull-requests: write
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.12"]
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools
+          pip install -e .[dev]
+
+      - name: Run non-GUI tests (test_00*.py)
+        working-directory: tests
+        run: >
+          python3 -c "import glob, pytest, sys; sys.exit(pytest.main(glob.glob('test_00*.py') + ['-v', '--disable-warnings']))"

shinestacker-0.2.0.post1.dev1/.github/workflows/release.yml

@@ -0,0 +1,73 @@
+---
+
+name: Create new release
+
+permissions:
+  contents: write
+  packages: write
+  pull-requests: write
+
+on:
+  push:
+    tags:
+      - v**
+
+jobs:
+  publish-release:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.12"]
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pyinstaller
+          pip install -e .[dev]
+
+      - name: Build and package release
+        working-directory: scripts
+        run: |
+          python build_release.py
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: shinestacker-${{ matrix.os }}
+          path: dist/shinestacker-release.zip
+
+  create-release:
+    needs: publish-release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+
+      - name: Prepare release assets
+        run: |
+          mkdir -p release_assets
+          cp artifacts/shinestacker-ubuntu-latest/shinestacker-release.zip release_assets/shinestacker-ubuntu.zip
+          cp artifacts/shinestacker-windows-latest/shinestacker-release.zip release_assets/shinestacker-windows.zip
+          cp artifacts/shinestacker-macos-latest/shinestacker-release.zip release_assets/shinestacker-macos.zip
+          ls -la release_assets/
+
+      - name: Create release
+        uses: softprops/action-gh-release@v1
+        with:
+          draft: true
+          files: |
+            release_assets/shinestacker-ubuntu.zip
+            release_assets/shinestacker-windows.zip
+            release_assets/shinestacker-macos.zip

shinestacker-0.2.0.post1.dev1/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/*
+*/__pycache__/*
+*.pyc
+.ipynb_checkpoints/*
+*/.ipynb_checkpoints/*
+*/*/.ipynb_checkpoints/*
+*/*/*/.ipynb_checkpoints/*
+anaconda_projects
+tests/output/*
+tests/plots/*
+tests/noise-map/*
+sandbox/img-test/*
+*/logs/*
+.DS_Store
+.virtual_documents
+*.egg-info/
+build/
+dist/
+.eggs/
+src/focusstack/_version.py
+*~
+*.spec
+logs

shinestacker-0.2.0.post1.dev1/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+This page reports the main releases only and the main changes therein.
+
+---
+
+## [v0.2.0] - 2025-07-27
+**Stability improvements and new package name**
+
+### Changes
+
+* first release with new name ShineStacker
+* added BRISK detector/descriptor alignment method
+* improved stability by adding more validation controls to alignment configuration
+* some bug fixes
+* minor restyling
+
+---
+
+## [v0.1.4] - 2025-07-23
+**Bug fixes and alignment improvements**
+
+### Changes
+
+* fixed recently introduced bugs in the alignment module
+* disabled ECC refinement, too unstable
+* improvement rigid alignment with more precise matrix
+* some minor bug fixes
+* removed dependence on termcolor external module
+* some internal code cleanup
+
+---
+
+## [v0.1.1] - 2025-07-20
+**Optimized image alignment**
+
+### Changes
+
+* Faster alignment with image subsample enables
+* Alignment refinement via ECC transform enabled
+* GUI opens new project dialog at startup
+* fixed color logging for windowed app
+*  bug fixes
+
+---
+
+## [v0.1.0] - 2025-07-19
+**First relatively stable and usable GUI release**
+
+### Changes
+- several stability improvements
+- several bug fixes
+
+
+---

shinestacker-0.2.0.post1.dev1/LICENSE

@@ -0,0 +1 @@
+The software is provided as is under the GNU Lesser General Public License v3.0.

shinestacker-0.2.0.post1.dev1/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: shinestacker
+Version: 0.2.0.post1.dev1
+Summary: ShineStacker
+Author-email: Luca Lista <luka.lista@gmail.com>
+License-Expression: LGPL-3.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: argparse
+Requires-Dist: imagecodecs
+Requires-Dist: ipywidgets
+Requires-Dist: jsonpickle
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: opencv_python
+Requires-Dist: pillow
+Requires-Dist: psdtags
+Requires-Dist: PySide6
+Requires-Dist: scipy
+Requires-Dist: tifffile
+Requires-Dist: tqdm
+Requires-Dist: setuptools-scm
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# Shine Stacker Processing Framework
+
+[![CI multiplatform](https://github.com/lucalista/shinestacker/actions/workflows/ci-multiplatform.yml/badge.svg)](https://github.com/lucalista/shinestacker/actions/workflows/ci-multiplatform.yml)
+
+<img src='https://raw.githubusercontent.com/lucalista/shinestacker/main/img/flies.gif' width="400">  <img src='https://raw.githubusercontent.com/lucalista/shinestacker/main/img/flies_stack.jpg' width="400">
+
+## Documentation
+
+📖 [Main documentation](https://github.com/lucalista/shinestacker/blob/main/docs/main.md) • 📝 [Changelog](https://github.com/lucalista/shinestacker/blob/main/CHANGELOG.md)
+
+
+# Credits:
+
+The main pyramid stack algorithm was inspired by the [Laplacian pyramids method](https://github.com/sjawhar/focus-stacking) implementation by Sami Jawhar. The latest implementation was rewritten from the original code that was used under permission of the author for initial versions of this package.
+
+# Resources
+
+* [Pyramid Methods in Image Processing](https://www.researchgate.net/publication/246727904_Pyramid_Methods_in_Image_Processing), E. H. Adelson, C. H. Anderson,  J. R. Bergen, P. J. Burt, J. M. Ogden, RCA Engineer, 29-6, Nov/Dec 1984
+Pyramid methods in image processing
+* [A Multi-focus Image Fusion Method Based on Laplacian Pyramid](http://www.jcomputers.us/vol6/jcp0612-07.pdf), Wencheng Wang, Faliang Chang, Journal of Computers 6 (12), 2559, December 2011
+* Another [original implementation on GitHub](https://github.com/bznick98/Focus_Stacking) by Zongnan Bao
+
+# License
+
+The software is provided as is under the [GNU Lesser General Public License v3.0](https://choosealicense.com/licenses/lgpl-3.0/).
+

shinestacker-0.2.0.post1.dev1/README.md

@@ -0,0 +1,26 @@
+# Shine Stacker Processing Framework
+
+[![CI multiplatform](https://github.com/lucalista/shinestacker/actions/workflows/ci-multiplatform.yml/badge.svg)](https://github.com/lucalista/shinestacker/actions/workflows/ci-multiplatform.yml)
+
+<img src='https://raw.githubusercontent.com/lucalista/shinestacker/main/img/flies.gif' width="400">  <img src='https://raw.githubusercontent.com/lucalista/shinestacker/main/img/flies_stack.jpg' width="400">
+
+## Documentation
+
+📖 [Main documentation](https://github.com/lucalista/shinestacker/blob/main/docs/main.md) • 📝 [Changelog](https://github.com/lucalista/shinestacker/blob/main/CHANGELOG.md)
+
+
+# Credits:
+
+The main pyramid stack algorithm was inspired by the [Laplacian pyramids method](https://github.com/sjawhar/focus-stacking) implementation by Sami Jawhar. The latest implementation was rewritten from the original code that was used under permission of the author for initial versions of this package.
+
+# Resources
+
+* [Pyramid Methods in Image Processing](https://www.researchgate.net/publication/246727904_Pyramid_Methods_in_Image_Processing), E. H. Adelson, C. H. Anderson,  J. R. Bergen, P. J. Burt, J. M. Ogden, RCA Engineer, 29-6, Nov/Dec 1984
+Pyramid methods in image processing
+* [A Multi-focus Image Fusion Method Based on Laplacian Pyramid](http://www.jcomputers.us/vol6/jcp0612-07.pdf), Wencheng Wang, Faliang Chang, Journal of Computers 6 (12), 2559, December 2011
+* Another [original implementation on GitHub](https://github.com/bznick98/Focus_Stacking) by Zongnan Bao
+
+# License
+
+The software is provided as is under the [GNU Lesser General Public License v3.0](https://choosealicense.com/licenses/lgpl-3.0/).
+

shinestacker-0.2.0.post1.dev1/docs/alignment.md

@@ -0,0 +1,74 @@
+# Alignment and registration: scale, tanslation and rotation correction, or full perspective correction
+
+```python
+job.add_action(Actions("align", [AlignFrames(*options)])
+```
+Arguments for the constructor ```AlignFrames``` of are:
+* ```feature_config``` (optional, default: ```None```): a dictionary specifying the following parameters, with the corresponding default values:
+```python
+{
+    'detector': DETECTOR_SIFT,
+    'descriptor': DESCRIPTOR_SIFT
+}
+```
+* ```detector``` (optional): the feature detector is used to find matches. See [Feature Detection and Description](https://docs.opencv.org/4.x/db/d27/tutorial_py_table_of_contents_feature2d.html) for more details. Possible values are:
+  * ```DETECTOR_SIFT``` (default): [Scale-Invariant Feature Transform](https://docs.opencv.org/4.x/da/df5/tutorial_py_sift_intro.html)]
+  * ```DETECTOR_ORB```: [Oriented FAST and Rotated BRIEF](https://docs.opencv.org/4.x/d1/d89/tutorial_py_orb.html)
+  * ```DETECTOR_SURF```: [Speeded-Up Robust Features](https://docs.opencv.org/3.4/df/dd2/tutorial_py_surf_intro.html)
+  * ```DETECTOR_AKAZE```: [AKAZE local features matching](https://docs.opencv.org/3.4/db/d70/tutorial_akaze_matching.html)
+  * ```DETECTOR_BRISK```: [Binary Robust Invariant Scalable Keypoints](https://medium.com/analytics-vidhya/feature-matching-using-brisk-277c47539e8)
+* ```descriptor``` (optional): the feature descriptor is used to find matches. Possible values are:
+  * ```DESCRIPTOR_SIFT``` (default)
+  * ```DESCRIPTOR_ORB```
+  * ```DESCRIPTOR_AKAZE```
+  * ```DESCRIPTPR_BRISK```
+
+  For a more quantitative comparison of performances of the different methods, consult the publication: [S. A. K. Tareen and Z. Saleem, "A comparative analysis of SIFT, SURF, KAZE, AKAZE, ORB, and BRISK", doi:10.1109/ICOMET.2018.8346440](https://ieeexplore.ieee.org/document/8346440)
+
+```matching_config``` (optional, default; ```None```): a dictionary specifying the following parameters, with the corresponding default values:
+```python
+{
+    'match_method': MATCHING_KNN,
+    'flann_idx_kdtree': 2,
+    'flann_trees': 5,
+    'flann_checks': 50,
+    'threshold': 0.75
+}
+```
+* ```match_method``` (optional): the method used to find matches. See [Feature Matching](https://docs.opencv.org/4.x/dc/dc3/tutorial_py_matcher.html) for more details. Possible values are:
+  * ```MATCHING_KNN``` (default): [Feature Matching with FLANN](https://docs.opencv.org/3.4/d5/d6f/tutorial_feature_flann_matcher.html)
+  * ```MATCHING_NORM_HAMMING```: [Use Hamming distance](https://docs.opencv.org/4.x/d2/de8/group__core__array.html#ggad12cefbcb5291cf958a85b4b67b6149fa4b063afd04aebb8dd07085a1207da727)
+* ```flann_idx_kdtree``` (optional, default: 2): parameter used by the FLANN matching algorithm.
+* ```flann_tree``` (optional, default: 5): parameter used by the FLANN matching algorithm.
+* ```flann_checks``` (optional, default: 50): parameter used by the FLANN matching algorithm.
+* ```threshold``` (optional, default: 0.75): parameter used to select good matches. See [Feature Matching](https://docs.opencv.org/4.x/dc/dc3/tutorial_py_matcher.html) for more details. 
+
+* ```alignment_config``` (optional, default; ```None```): a dictionary specifying the following parameters, with the corresponding default values:
+```python
+{
+    'transform': ALIGN_RIGID,
+    'align_methid': RANSAC,
+    'rans_threshold': 5.0,
+    'border_mode': BORDER_REPLICATE_BLUR,
+    'border_value': (0, 0, 0, 0),
+    'border_blur': 50
+}
+```
+* ```transform``` (optional): the transformation applied to register images. Possible values are:
+  * ```ALIGN_RIGID``` (default): allow scale, tanslation and rotation correction. This should be used for image acquired with tripode or microscope.
+  * ```ALIGN_HOMOGRAPHY```: allow full perspective correction. This should be used for images taken with hand camera.
+* ```align_method``` (optional): the method used to find matches. Valid options are:
+  * ```RANSAC``` (*Random Sample Consensus*)
+  * ```LMEDS``` (*Least Medians of Squares*)
+* ```rans_threshold``` (optional, default: 5.0): parameter used if ```ALIGN_HOMOGRAPHY``` is choosen as tansformation, see [Feature Matching + Homography to find Objects](https://docs.opencv.org/3.4/d1/de0/tutorial_py_feature_homography.html) for more details.
+* ```subsample``` (optional, default: 4): subsample image for faster alignment. Faster, but alignment could be less accurate.
+* ```fast_subsampling``` (optiona, default: ```False```): perform fast image subsampling without interpolation. Used if ```subsample``` is set to ```True```.
+* ```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:
+  * ```BORDER_CONSTANT```: pad the image with a constant value. The border value is specified with the parameter ```border_value```.
+  * ```BORDER_REPLICATE```: the rows and columns at the very edge of the original are replicated to the extra border.
+  * ```BORDER_REPLICATE_BLUR``` (default): same as above, but the border is blurred. The amount of blurring is specified by the parameter ```border_blur```.
+* ```border_value``` (optional, default: ```(0, 0, 0, 0)```): border value. See [Adding borders to your images](https://docs.opencv.org/3.4/dc/da3/tutorial_copyMakeBorder.html) for more details.
+* ```border_blur``` (optional, default: ```50```): amount of border blurring, in pixels. Only applied if ```border_mode``` is set to ```BORDER_REPLICATE_BLUR```, which is the default option.
+* ```plot_summary```  (optional, default: ```False```): if ```True```, plot a summary histogram with number of matches in each frame. May be useful for inspection and debugging.
+* ```plot_matches```  (optional, default: ```False```): if ```True```, for each image matches with reference frame are drawn. May be useful for inspection and debugging.
+* ```enabled``` (optional, default: ```True```): allows to switch on and off this module.

shinestacker-0.2.0.post1.dev1/docs/balancing.md

@@ -0,0 +1,25 @@
+# Luminosity and color balance
+
+```python
+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.
+* ```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
+{
+    'min': 0,
+    'max': -1
+}
+```
+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```.
+* ```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.
+   * ```BALANCE_GAMMA```: a gamma correction, i.e.: a power law, is applied in order to balance the average intensity of the corrected images to reference image in the specified channels. The gamma correction avoids saturation of low or high intensity pixels which may occur for a linear coorection, but may introduce more distortion than a linear mapping.
+   * ```BALANCE_MATCH_HIST```: the intensity histogram of the corrected image matches the histogram of the reference image in the specified channels. This options shoudl better be used with the value ```BALANCE_RGB``` for the ```channel``` option. If this option is specified, the options ```intensity_interval``` and ```subsample```are not used.  This option may be somewhat slow for 16-bit images.
+* ```plot_histograms```  (optional, default: ```False```): if ```True```, plot hisograms for each image and for the reference frame.
+* ```plot_summary```  (optional, default: ```False```): if ```True```, plot a summary of the corrections.
+* ```enabled``` (optional, default: ```True```): allows to switch on and off this module. 

shinestacker-0.2.0.post1.dev1/docs/focus_stacking.md

@@ -0,0 +1,54 @@
+# Focus Stacking
+
+```python
+job.add_action(FocusStack(name, stacker, *options))
+```
+Arguments for the constructor of ```FocusStack``` are:
+* ```name```: the name of the action, used for printout, and possibly for output path
+* ```stacker```: an object defining the focus stacking algorithm. Can be ```PyramidStack```, ```PyramidBlock``` or ```DepthMapStack```, see below for possible algorithms. 
+* ```input_path``` (optional): the subdirectory within ```working_path``` that contains input images to be processed. If not specified, the last output path is used, or, if this is the first action, the ```input_path``` specified with the ```StackJob``` construction is used. If the ```StackJob``` specifies no ```input_path```, at least the first action must specify an  ```input_path```.
+* ```output_path``` (optional): the subdirectory within ```working_path``` where aligned images are written. If not specified,  it is equal to  ```name```.
+* ```working_path```: the directory that contains input and output image subdirectories. If not specified, it is the same as ```job.working_path```.
+* ```exif_path``` (optional): if specified, EXIF data are copied to the output file from file in the specified directory. If not specified, it is the source directory used as input for the first action. If set equal to ```''``` no EXIF data is saved.
+* ```denoise``` (optoinal): if specified, a denois algorithm is applied. A value of 0.75 to 1.00 does not reduce details in an appreciable way, and is suitable for modest noise reduction. denoise may be useful for 8-bit images, or for images taken at large ISO. 16-bits images at low ISO usually don't require denoise. See [Image Denoising](https://docs.opencv.org/3.4/d5/d69/tutorial_py_non_local_means.html) for more details.
+* ```prefix``` (optional): if specified, the specified string is pre-pended to the file name. May be useful if more algorithms are ran, and different file names are used for the output of different algorithms.
+* ```enabled``` (optional, default: ``True```): allows to switch on and off this module.
+
+## Focus Stacking in bunches of frames
+
+```python
+job.add_action(FocusStackBunch(name, stacker, *options))
+```
+Arguments for the constructor of ```FocusStackBunch``` are:
+* ```name```: the name of the action, used for printout, and possibly for output path
+* ```stacker```: an object defining the focus stacking algorithm. Can be ```PyramidStack```, ```PyramidStack``` or ```DepthMapStack```, see below for possible algorithms. 
+* ```input_path``` (optional): the subdirectory within ```working_path``` that contains input images to be processed. If not specified, the last output path is used, or, if this is the first action, the ```input_path``` specified with the ```StackJob``` construction is used. If the ```StackJob``` specifies no ```input_path```, at least the first action must specify an  ```input_path```.
+* * ```output_path``` (optional): the subdirectory within ```working_path``` where aligned images are written. If not specified,  it is equal to  ```name```.
+* ```working_path```: the directory that contains input and output image subdirectories. If not specified, it is the same as ```job.working_path```.
+* ```exif_path``` (optional): if specified, EXIF data are copied to the output file from file in the specified directory. If not specified, it is the source directory used as * ```frames``` (optional, default: 10): the number of frames in each bunch that are stacked together.
+* ```frames``` (optional, default: 10): the number of frames that are fused together. 
+* ```overlap``` (optional, default: 0): the number of overlapping frames between a bunch and the following one. 
+* ```denoise``` (optoinal): if specified, a denois algorithm is applied. A value of 0.75 to 1.00 does not reduce details in an appreciable way, and is suitable for modest noise reduction. See [Image Denoising](https://docs.opencv.org/3.4/d5/d69/tutorial_py_non_local_means.html) for more details
+* ```prefix``` (optional): if specified, the specified string is pre-pended to the file name. May be useful if more algorithms are ran, and different file names are used for the output of different algorithms.
+* ```enabled``` (optional, default: ```True```): allows to switch on and off this module.
+
+## Stack algorithms
+
+```PyramidStack```, Laplacian pyramid focus stacking algorithm, optimized implementation
+
+Arguments for the constructor are:
+   * ```pyramid_min_size``` (optional, default: 32)
+   * ```kernel_size``` (optional, default: 5)
+   * ```gen_kernel``` (optional, default: 0.4)
+   * ```float_type``` (optional, default: ```FLOAT_32```, possible values: ```FLOAT_32```, ```FLOAT_64```): precision for internal image representation
+
+```DepthMapStack```, Depth map focus stacking algorithm
+
+Arguments for the constructor are:
+   * ```map_type``` (optional), possible values are  ```MAP_MAX``` (default) and ```MAP_AVERAGE```. ```MAP_MAX``` select for wach pixel the layer which has the best focus. ```MAP_AVERAGE``` performs for each pixel an average of all layers weighted by the quality of focus.
+   * ```energy``` (optional), possible values are ```ENERGY_LAPLACIAN``` (default) and ```ENERGY_SOBEL```.
+   * ```kernel_size``` (optional, default: 5) size in pixels of Laplacian kernel.
+   * ```blur_size``` (optional, default: 5) size in pixels of the pre-Laplacian Gaussian blur.
+   * ```smooth_size``` (optional, default: 15) size of energy smoothing.
+   * ```temperature``` (optional, default: 0.1) controls fision transition: lower value means sharper transitions.
+   * ```levels``` (optional, defauls: 3) number of levels for the Laplacian pyramid.

shinestacker-0.2.0.post1.dev1/docs/gui.md

@@ -0,0 +1,131 @@
+# Graphical User Interface
+
+## Introduction
+FocusStack processes focus-bracketed images in two phases:
+* **Project**: Batch processing (alignment/balancing/stacking)
+* **Retouch**: Layer-based refinement
+> [!NOTE]
+> Advanced processing details in [main documentation](main.md).
+
+The batch processing supports image alignment, color and luminosity balance, vignetting removal,
+noisy pixel masking.
+
+## Starting
+
+* If the python package is donwloaded and installed, the GUI can start either from a console command line :
+
+```console
+> focusstack
+```
+
+* If the app is dowloaded from the [releases page](https://github.com/lucalista/focusstack/releases), after the  ```zip``` archive is uncompressed, just double-click the app icon.
+
+<img src='../img/gui-finder.png' width="300">
+
+**Platform Tip**: Windows apps are inside `/focusstack/`, macOS/Linux apps are directly in the uncompressed folder.
+
+The GUI has two main working areas: 
+
+* *Project* 
+* *Retouch*
+
+Switching from *Project* to *Retouch* can be done from the *FocusStack* main menu.
+
+## Project area
+
+When the app starts, it proposes to create a new project.
+
+<img src='../img/gui-project-new.png' width="600">
+
+### Creating Projects
+1. Select source folder (JPEG/TIFF 8/16-bit)
+2. Configure job actions (auto-saved in project file)
+3. Run processing:
+   - Real-time logs & progress bar
+   - Thumbnail previews for each stage
+
+<img src='../img/flow-diagram.png' width="900" alt="FocusStack workflow: Source images → Alignment → Balancing → Stacking">
+
+> **Large Set Tip**: For 100+ images:
+> - Split into 10-15 image "bunches" 
+> - Set frame overlap (default: 2 frames)
+> - Combine intermediate results later
+
+> 💡 **RAM Warning**: >15 images may need 16GB+ RAM. Use smaller batches if needed.
+
+The newly created project consists of a single job that contains more actions.
+Each action produces a folder as output that has, by default, the action's name.
+Some actions can be combined in order to produce a single intermediate output (alignment, balancing, etc.).
+
+**Action Outputs**: 📁 `aligned-balanced/` | 📁 `bunches/` | 📁 `stacked/`
+
+> **Pro Tip**: Duplicate jobs when processing similar image sets to save configuration time. You can run multiple jobs in sequence.
+
+It is possible to run a single job, or all jobs within a project.
+
+<img src='../img/gui-project-run.png' width="600">
+
+### Project Run Tabs
+
+1. Job progress bar
+2. Real-time log viewer
+3. Retouch button (enabled after processing)
+
+When the job finishes, a *Retouch* button is enabled, which opens the output image into the retouch area.
+
+## Retouch area
+
+<img src='../img/gui-retouch.png' width="600">
+
+### Brush Properties
+Adjust in the top toolbar:
+- **Size**: Brush diameter (px)
+- **Hardness**: Edge softness (0-100%)
+- **Opacity**: Paint transparency
+- **Flow**: Paint accumulation rate
+
+> 💡 Pro Tip: Use low opacity/flow (20-40%) for subtle corrections
+
+### Retouch Workflow
+
+1. **Navigate**: 
+   - Zoom/pan to defect area
+   - Toggle between master/source (`X`)
+2. **Correct defects/artifacts**:**:
+   - Select source layer with clean area
+   - Adjust brush properties (size/hardness/opacity)
+   - Paint over defects
+   - Use `Ctrl+Z` to undo strokes
+3. **Verify**:
+   - Toggle master view (`M`) to check results
+   - Compare before/after with `L`/`M` toggle
+3. **Export**:
+   - ✅ Final image: Single TIFF/JPEG 
+   - 🗂️ Editable: Multilayer TIFF (large)
+
+| Action              | Shortcut                  |
+|---------------------|---------------------------|
+| Zoom in/out         | `Ctrl` + `+`/`- or mouse wheel          |
+| Reset view          | `Ctrl` + `0`              |
+| Pan                 | `Space` + mouse drag      |
+| Prev./next layer    | `Up`/`Down` arrows        |
+| View master layer   | `M`                       |
+| View source layer   | `L`                       |
+| Toggle master ↔ source | `X`                    |
+
+See help menu for complete list of shortcuts.
+
+**Export Formats**:
+- Single TIFF: Final image (highest quality)
+- Single JPEG: For web and quick preview (lower quality)
+- Multilayer TIFF: Preserves all layers (large file)
+
+**EXIF metadata**:
+* EXIF data can be imported from source images and saved with final file.
+
+## Final retouch
+
+The final retouch, including color and luminosity balance, sharpness enhancement and
+so on can be applied with your favorite image processing application, like [GIMP](https://www.gimp.org/)
+or other.
+

shinestacker-0.2.0.post1.dev1/docs/job.md

@@ -0,0 +1,33 @@
+# Job creation
+
+Create a job, then schedule the desired actions in a job, then run the job.
+
+```python
+job = StackJob(name, working_path [, input_path])
+```
+
+Arguments are:
+* ```working_path```: the directory that contains input and output images, organized in subdirectories as specified by each action
+* ```name```: the name of the job, used for printout
+* ```input_path``` (optional): the subdirectory within ```working_path``` that contains input images for subsequent action. If not specified, at least the first action must specify an ```input_path```.
+* ```callbacks``` (optional, default: ```None```): dictionary of callback functions for internal use. If equal to ```'tqdm'```, a progress bar is shown in either text mode or jupyter notebook.
+* ```enabled``` (optional, default: ```True```): allows to switch on and off all actions within a job.
+
+# Schedule multiple actions based on a reference image: align and/or balance images
+
+The class ```CombinedActions``` runs multiple actions on each of the frames appearing in a path.
+
+```python
+job.add_action(CombinedActions(name, [...], *options))
+```
+Arguments for the constructor of ```CombinedActions``` are for the :
+* ```name```: the name of the action, used for printout, and possibly for output path.
+* ```actions```: array of action object to be applied in cascade.
+* ```input_path``` (optional): the subdirectory within ```working_path``` that contains input images to be processed. If not specified, the last output path is used, or, if this is the first action, the ```input_path``` specified with the ```StackJob``` construction is used. If the ```StackJob``` specifies no ```input_path```, at least the first action must specify an  ```input_path```.
+* ```output_path``` (optional): the subdirectory within ```working_path``` where aligned images are written. If not specified,  it is equal to  ```name```.
+* ```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.
+* ```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.