tse-tools 1.0.0__tar.gz

tse_tools-1.0.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Samuli Vuorinen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tse_tools-1.0.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: tse-tools
+Version: 1.0.0
+Summary: Toolkit for aligning, stacking, and filtering total solar eclipse photographs.
+Author-email: Samuli Vuorinen <samuli.vuorinen@iki.fi>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/naavis/eclipsetools/
+Project-URL: Repository, https://github.com/naavis/eclipsetools/
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: rawpy~=0.25.0
+Requires-Dist: matplotlib~=3.10.3
+Requires-Dist: numpy~=2.2.6
+Requires-Dist: opencv-python-headless~=4.11.0
+Requires-Dist: joblib~=1.5.1
+Requires-Dist: click~=8.1.7
+Requires-Dist: tifffile~=2025.6.11
+Requires-Dist: tqdm~=4.67.1
+Requires-Dist: scipy~=1.15.2
+Requires-Dist: scikit-learn~=1.7.0
+Requires-Dist: numba~=0.61.2
+Requires-Dist: numba-progress~=1.1.0
+Requires-Dist: scikit-image~=0.25.2
+Dynamic: license-file
+
+# Total Solar Eclipse Toolkit
+
+Toolkit for aligning and processing total solar eclipse photographs.
+
+## Installation
+
+```bash
+pip install tse-tools
+```
+
+## Usage
+
+```bash
+tse-tools --help
+```
+
+## Development
+
+### Setting up
+
+Create a virtual environment and install the package in editable mode with the
+development dependencies:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate      # Windows: .venv\Scripts\activate
+pip install -e . --group dev
+```
+
+This installs the runtime dependencies, the test tooling, and `black`, and puts
+the `tse-tools` command on your `PATH` (pointing at your working tree).
+
+### Running in development
+
+```bash
+tse-tools --help               # or: python -m eclipsetools.cli --help
+```
+
+### Formatting
+
+```bash
+black src tests
+```
+
+### Tests
+
+```bash
+pytest -n auto
+```
+
+The alignment tests depend on the binary asset `tests/images/eclipse_5ms.CR3`.

tse_tools-1.0.0/README.md

@@ -0,0 +1,51 @@
+# Total Solar Eclipse Toolkit
+
+Toolkit for aligning and processing total solar eclipse photographs.
+
+## Installation
+
+```bash
+pip install tse-tools
+```
+
+## Usage
+
+```bash
+tse-tools --help
+```
+
+## Development
+
+### Setting up
+
+Create a virtual environment and install the package in editable mode with the
+development dependencies:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate      # Windows: .venv\Scripts\activate
+pip install -e . --group dev
+```
+
+This installs the runtime dependencies, the test tooling, and `black`, and puts
+the `tse-tools` command on your `PATH` (pointing at your working tree).
+
+### Running in development
+
+```bash
+tse-tools --help               # or: python -m eclipsetools.cli --help
+```
+
+### Formatting
+
+```bash
+black src tests
+```
+
+### Tests
+
+```bash
+pytest -n auto
+```
+
+The alignment tests depend on the binary asset `tests/images/eclipse_5ms.CR3`.

tse_tools-1.0.0/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "tse-tools"
+version = "1.0.0"
+description = "Toolkit for aligning, stacking, and filtering total solar eclipse photographs."
+authors = [
+    { name = "Samuli Vuorinen", email = "samuli.vuorinen@iki.fi" }
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Astronomy",
+    "Topic :: Scientific/Engineering :: Image Processing",
+    "Operating System :: OS Independent",
+]
+readme = 'README.md'
+license = 'MIT'
+license-files = ['LICENSE.md']
+requires-python = ">=3.11"
+dependencies = [
+    "rawpy ~= 0.25.0",
+    "matplotlib ~= 3.10.3",
+    "numpy ~= 2.2.6",
+    "opencv-python-headless ~= 4.11.0",
+    "joblib ~= 1.5.1",
+    "click ~= 8.1.7",
+    "tifffile ~= 2025.6.11",
+    "tqdm ~= 4.67.1",
+    "scipy ~= 1.15.2",
+    "scikit-learn ~= 1.7.0",
+    "numba ~= 0.61.2",
+    "numba-progress ~= 1.1.0",
+    "scikit-image ~= 0.25.2",
+]
+
+[dependency-groups]
+test = [
+    "pytest ~= 8.4.0",
+    "pytest-xdist ~= 3.7.0",
+]
+dev = [
+    { include-group = "test" },
+    "black ~= 25.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/naavis/eclipsetools/"
+Repository = "https://github.com/naavis/eclipsetools/"
+
+[project.scripts]
+tse-tools = "eclipsetools.cli:main"
+
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["eclipsetools*"]

tse_tools-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tse_tools-1.0.0/src/eclipsetools/alignment/phase_correlation.py

@@ -0,0 +1,101 @@
+import functools
+
+import numpy as np
+
+from eclipsetools.preprocessing.masking import hann_window_mask
+
+
+def phase_correlate_with_low_pass(
+    img_a: np.ndarray,
+    img_b: np.ndarray,
+    low_pass_sigma: float | None = None,
+) -> np.ndarray:
+    """
+    Phase correlate two images with optional low-pass filtering in the frequency domain. This method was suggested
+    by Druckmüller and Druckmüllerová. The correlation peak is further refined by calculating the center of mass
+    in a 5x5 window around the initial peak.
+    :param img_a: First image
+    :param img_b: Second image
+    :param low_pass_sigma: Standard deviation for Gaussian low-pass filter in frequency domain. The lower the value,
+                           the stronger the low-pass filtering. If None, no low-pass filtering is applied.
+    :return: Translation vector (dy, dx) indicating how much the second image is shifted relative to the first.
+    """
+    assert img_a.shape == img_b.shape
+
+    window = hann_window_mask(img_a.shape)
+
+    img_a_win = window * img_a
+    img_a_win -= img_a_win.mean()
+    img_a_win /= img_a_win.std()
+
+    img_b_win = window * img_b
+    img_b_win -= img_b_win.mean()
+    img_b_win /= img_b_win.std()
+
+    fft1 = np.fft.rfft2(img_a_win)
+    fft2 = np.fft.rfft2(img_b_win)
+
+    offset = 0.01 * np.max(np.abs(fft1))
+    cross_power_spectrum = (
+        fft1 * np.conjugate(fft2) / ((np.abs(fft1) + offset) * (np.abs(fft2) + offset))
+    )
+
+    if low_pass_sigma:
+        cross_power_spectrum *= _gaussian_weights(low_pass_sigma, img_a.shape)
+
+    phase_correlation = np.abs(np.fft.irfft2(cross_power_spectrum, s=img_a.shape))
+    phase_correlation = np.fft.ifftshift(phase_correlation)
+
+    initial_peak = np.unravel_index(np.argmax(phase_correlation), img_a.shape)
+    subpixel_peak = _center_of_mass(
+        phase_correlation,
+        (int(initial_peak[0]), int(initial_peak[1])),
+        5,
+    )
+
+    return np.array(img_a.shape) / 2 - subpixel_peak
+
+
+@functools.cache
+def _gaussian_weights(sigma: float, image_shape: tuple) -> np.ndarray:
+    fy = np.fft.rfftfreq(image_shape[1])
+    fx = np.fft.fftfreq(image_shape[0])
+    fy_grid, fx_grid = np.meshgrid(fy, fx)
+    freq_squared = fy_grid**2 + fx_grid**2
+    gaussian_weighting = np.exp(-0.5 * freq_squared / (sigma**2), dtype=np.float32)
+    return gaussian_weighting
+
+
+def _center_of_mass(
+    image: np.ndarray,
+    center_point: tuple[int, int],
+    window_size: int,
+) -> tuple[float, float]:
+    height, width = image.shape
+    y0, x0 = center_point
+    half_size = window_size // 2
+
+    # Generate wrapped indices
+    y_indices = np.arange(y0 - half_size, y0 + half_size + 1) % height
+    x_indices = np.arange(x0 - half_size, x0 + half_size + 1) % width
+
+    # Extract wrapped region
+    region = image[np.ix_(y_indices, x_indices)]
+
+    # Create coordinate grid (local to the region)
+    y_grid, x_grid = np.indices(region.shape)
+
+    # Compute total intensity
+    total_mass = region.sum()
+    if total_mass == 0:
+        return float(y0), float(x0)  # or None
+
+    # Compute local CoM
+    y_com_local = (y_grid * region).sum() / total_mass
+    x_com_local = (x_grid * region).sum() / total_mass
+
+    # Map back to global coordinates (using wrapping)
+    y_com_global = np.float32((y0 - half_size + y_com_local) % height)
+    x_com_global = np.float32((x0 - half_size + x_com_local) % width)
+
+    return y_com_global, x_com_global

tse_tools-1.0.0/src/eclipsetools/alignment/transform.py

@@ -0,0 +1,104 @@
+import cv2
+import numpy as np
+
+from eclipsetools.alignment.phase_correlation import phase_correlate_with_low_pass
+
+
+def find_transform(
+    ref_image: np.ndarray,
+    image: np.ndarray,
+    low_pass_sigma: float,
+    allow_scale: bool,
+) -> tuple[float, float, tuple[float, float]]:
+    """
+    Find the scale, rotation, and translation between two images.
+
+    This function uses a multistep approach:
+    1. Find scale and rotation using log-polar transform and phase correlation
+    2. Apply the found scale and rotation to the image
+    3. Find the translation using phase correlation on the transformed image
+
+    :param ref_image: Reference image to align against
+    :param image: Image to be aligned
+    :param low_pass_sigma: Standard deviation for Gaussian low-pass filter in frequency domain when finding translation.
+    :param allow_scale: Allow estimating scale. If False, scale is assumed to be 1.0.
+    :return: Tuple containing (scale, rotation_angle_degrees, (dy, dx))
+             where dy, dx is the translation vector from the reference image to the aligned image.
+    """
+
+    ref_image_pad = _pad_with_zeros(ref_image)
+    image_pad = _pad_with_zeros(image)
+
+    shape = ref_image_pad.shape
+    shortest_side = np.min(shape)
+    radius = shortest_side // 8
+
+    # Step 1: Find scale and rotation
+    # We only need half of the log-polar FFTs, as they are symmetric
+    ref_fft_log_polar = _log_polar_fft(ref_image_pad, radius)[: shape[0] // 2, :]
+    image_fft_log_polar = _log_polar_fft(image_pad, radius)[: shape[0] // 2, :]
+
+    # Find shifts in the log-polar FFTs using phase correlation
+    shift_y, shift_x = phase_correlate_with_low_pass(
+        ref_fft_log_polar, image_fft_log_polar
+    )
+
+    # Recover rotation from the correlation result
+    rotation_degrees = -360.0 * shift_y / ref_fft_log_polar.shape[0]
+
+    # Recover scale from the correlation result
+    k_log = radius / np.log(radius)
+    scale = np.exp(-shift_x / k_log) if allow_scale else 1.0
+
+    # Step 2: Apply scale and rotation to the image
+    rotate_scale_matrix = cv2.getRotationMatrix2D(
+        (image_pad.shape[1] // 2, image_pad.shape[0] // 2),
+        -rotation_degrees,
+        1.0 / scale,
+    )
+
+    translated_image = cv2.warpAffine(
+        image_pad,
+        rotate_scale_matrix,
+        dsize=(image_pad.shape[1], image_pad.shape[0]),
+        flags=cv2.INTER_LINEAR,
+        borderMode=cv2.BORDER_CONSTANT,
+        borderValue=[0, 0, 0],
+    ).astype(np.float32)
+
+    # Step 3: Find translation between reference and transformed image
+    translation_y, translation_x = phase_correlate_with_low_pass(
+        ref_image_pad, translated_image, low_pass_sigma
+    )
+
+    return (
+        float(scale),
+        float(rotation_degrees),
+        (float(translation_y), float(translation_x)),
+    )
+
+
+def _pad_with_zeros(image: np.ndarray) -> np.ndarray:
+    assert len(image.shape) == 2, "Input image must be a 2D array (grayscale image)."
+    h, w = image.shape
+    longer_side = max(h, w)
+    padded = np.zeros((longer_side, longer_side), dtype=image.dtype)
+    y_offset = (longer_side - h) // 2
+    x_offset = (longer_side - w) // 2
+    padded[y_offset : y_offset + h, x_offset : x_offset + w] = image
+    return padded
+
+
+def _log_polar_fft(image: np.ndarray, radius: float) -> np.ndarray:
+    assert len(image.shape) == 2, "Input image must be a 2D array (grayscale image)."
+    fft_mag = np.abs(np.fft.fftshift(np.fft.fft2(image)))
+    # Amplitude spectra have very high values in the low frequencies, so we use logarithm to compress the range
+    fft_mag = np.log(1.0 + fft_mag)
+    log_polar = cv2.warpPolar(
+        src=fft_mag,
+        dsize=(0, 0),
+        center=(fft_mag.shape[1] // 2, fft_mag.shape[0] // 2),
+        maxRadius=radius,
+        flags=cv2.INTER_LINEAR | cv2.WARP_POLAR_LOG,
+    )
+    return log_polar

tse_tools-1.0.0/src/eclipsetools/cli.py

@@ -0,0 +1,20 @@
+import click
+
+from eclipsetools.commands.align import align_group
+from eclipsetools.commands.filter import filter_group
+from eclipsetools.commands.stack import stack_group
+from eclipsetools.commands.utils import utils_group
+
+
+@click.group(context_settings={"show_default": True})
+def main():
+    pass
+
+
+main.add_command(align_group)  # type: ignore
+main.add_command(filter_group)  # type: ignore
+main.add_command(stack_group)  # type: ignore
+main.add_command(utils_group)  # type: ignore
+
+if __name__ == "__main__":
+    main()