exhale-xrf 1.5.0__tar.gz

exhale_xrf-1.5.0/.ruff.toml

@@ -0,0 +1,22 @@
+target-version = "py310"
+line-length = 100
+extend-exclude = [
+    "exhale/*_ui.py",
+]
+
+[lint]
+select = [
+    "E301", "E302", "E303", "E304", "E305", "E306",
+    "E4", "E7", "E9", "F", "W",
+    "I", "B", "UP", "RUF100",
+]
+ignore = ["E501"]
+preview = true
+explicit-preview-rules = true
+
+[format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+skip-magic-trailing-comma = false
+docstring-code-format = false

exhale_xrf-1.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carl Troein, Tom Delaire, Bryan Falcones, Emanuel Larsson, Karina Thånell
+
+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.

exhale_xrf-1.5.0/MANIFEST.in

@@ -0,0 +1,21 @@
+include README.md
+include pyproject.toml
+include MANIFEST.in
+include run_exhale.py
+
+recursive-include exhale *.py
+recursive-include exhale/resources/icons *.png *.svg *.txt
+recursive-include exhale/resources/linux *.desktop
+recursive-include exhale/resources/licenses *
+include exhale/resources/*.jpg
+recursive-include exhale/resources/models *.json *.h5 *.pt
+
+exclude .gitignore
+
+prune .github
+prune build
+prune dist
+prune packaging
+prune exhale/resources/ui
+
+global-exclude __pycache__ *.py[cod]

exhale_xrf-1.5.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: exhale-xrf
+Version: 1.5.0
+Summary: Exhale, Efficient X-ray Hub Aiding Lung Explorations
+Author: Tom Delaire, Emanuel Larsson, Bryan Falcones, Karina Thånell
+Author-email: Carl Troein <carl.troein@mgeo.lu.se>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ctroein/exhale
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: packaging<27
+Requires-Dist: numpy<2.6
+Requires-Dist: scipy<1.19
+Requires-Dist: scikit-learn<1.10
+Requires-Dist: pandas<3.2
+Requires-Dist: h5py<3.17
+Requires-Dist: tifffile<2026.11
+Requires-Dist: imagecodecs<2026.11
+Requires-Dist: napari<0.11,>=0.10
+Requires-Dist: imageio<2.39
+Requires-Dist: pyqt6<6.13,>=6.7
+Requires-Dist: qtpy<2.5
+Requires-Dist: pyqtgraph<0.15,>=0.13.7
+Provides-Extra: stardist
+Requires-Dist: csbdeep<0.9; extra == "stardist"
+Requires-Dist: tensorflow==2.15.*; sys_platform == "win32" and extra == "stardist"
+Requires-Dist: tensorflow<2.21; sys_platform == "linux" and extra == "stardist"
+Requires-Dist: tensorflow<2.21; sys_platform == "darwin" and extra == "stardist"
+Requires-Dist: stardist<0.10; extra == "stardist"
+Provides-Extra: cellpose
+Requires-Dist: torch<2.16,>=2.8; extra == "cellpose"
+Requires-Dist: torchvision<0.30,>=0.23; extra == "cellpose"
+Requires-Dist: cellpose==4.2.1.1; extra == "cellpose"
+Provides-Extra: monai
+Requires-Dist: torch<2.16,>=2.8; extra == "monai"
+Requires-Dist: monai<1.7,>=1.6.1; extra == "monai"
+Dynamic: license-file
+
+# Exhale
+## Efficient X-ray Hub Aiding Lung Explorations
+
+<p align="center">
+  <img src="artwork/screenshots/segmentation_20261023.png"
+       alt="EXHALE segmentation results"
+       width="900">
+</p>
+
+This project aims to develop a specialized tool for investigating elemental aspects of chronic lung diseases. 
+
+From the [VINNOVA project
+description](https://www.vinnova.se/en/p/exhale--efficient-x-ray-hub-aiding-lung-explorations/):  
+The purpose of this project is to advance understanding and treatment of
+chronic lung diseases, leading causes of mortality worldwide, by
+characterizing elements in lung tissue suspected to impact their
+pathogenesis. The industrial partners TrulyLabs and AnaMar in collaboration
+with MAX IV, Lung Biology and Correlative Image Processing and Analysis
+(CIPA) fom Lund University, aim to streamline a workflow of X-ray imaging
+studies for lung diseases, making these methods more accessible for
+biomedical companies and clinical researchers.
+
+## Currect functionality
+
+* Loading HDF5 files with XRF data from the NanoMAX beamline at MAX IV.
+* Composing element maps into publication-ready figures.
+* Segmentation of cells and clustering of areas in element maps.
+
+## Installation
+
+### Linux
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) if needed,
+then choose the segmentation backends you want.
+
+For StarDist (TensorFlow):
+
+```bash
+uv tool install --python 3.12 'exhale-xrf[stardist]'
+```
+
+For Cellpose and MONAI U-Net (PyTorch; Cellpose also needs DINOv3):
+
+```bash
+uv tool install --python 3.12 --with-requirements https://raw.githubusercontent.com/ctroein/exhale/main/requirements-cellpose.txt 'exhale-xrf[cellpose,monai]'
+```
+
+For MONAI U-Net alone:
+
+```bash
+uv tool install --python 3.12 'exhale-xrf[monai]'
+```
+
+MONAI U-Net's trained weights are bundled; no model download is needed.
+
+To also include StarDist, use `'exhale-xrf[stardist,cellpose,monai]'` with the same additional
+requirements argument. Plain `exhale-xrf` installs viewing, composition and
+analysis of existing results without neural segmentation backends. Unavailable
+backends are disabled in the application.
+
+Run `exhale` to start the application. To add it to the current user's desktop
+environment and application menu:
+
+```bash
+exhale --install-desktop
+```
+
+To update the application and its selected backends:
+
+```bash
+uv tool upgrade exhale-xrf
+```
+
+On Linux, Settings also offers daily update checks and a Check now button.
+Checks notify you of newer stable releases without installing anything. For a
+writable uv tool installation owned by your account, Update now closes Exhale,
+runs the upgrade, checks startup, and reopens it. Normal project saving applies
+before closing. Other Exhale instances must be closed first. Update results and
+the log location are shown after restarting. Automatic checks can be disabled
+in Settings.
+
+uv retains the installation settings, including extras and additional
+requirements. To change backend selection, rerun `uv tool install` with the
+wanted extras and, for Cellpose, the requirements argument.
+
+To uninstall, remove the desktop/menu entry before removing the application:
+
+```bash
+exhale --remove-desktop
+uv tool uninstall exhale-xrf
+```
+
+### Windows
+
+Windows 10 or later with 64-bit compatibility is required. Download the
+`exhale-…-setup.exe` installer from the
+[GitHub releases page](https://github.com/ctroein/exhale/releases) and run it.
+
+The installer offers StarDist, Cellpose, both, or neither before setup. It
+downloads a private Python environment and the selected packages; internet
+access is required, but an existing Python or uv installation is not.
+Use the Start menu or optional desktop shortcut to launch EXHALE.
+
+Settings offers daily update checks, Check now, and Update now. Application
+updates preserve the selected backends and validate a new runtime before
+switching to it. You can also download and run a newer installer; use that to
+update the launcher/setup tools, change backends, or repair the installation.
+Uninstall through Windows Settings; the private runtime and shortcuts are
+removed while projects, trained models and application settings are retained.
+
+### macOS
+
+Download the Apple Silicon (`arm64`) or Intel (`x86_64`) DMG from the
+[GitHub releases page](https://github.com/ctroein/exhale/releases), drag
+EXHALE.app into Applications, and open it there. Setup downloads Python and the
+selected segmentation backends; neither Python nor uv needs to be installed
+beforehand. Intel Macs support StarDist but not the current Cellpose backend.
+The launcher requires macOS 13 or newer; Cellpose's PyTorch requires at least
+macOS 14 on Apple Silicon, and dependencies may require newer versions.
+
+The Mac app is not Developer ID signed or notarized. macOS may block its first
+launch; see [Apple's explanation and opening options](https://support.apple.com/102445).
+
+Subsequent launches open the installed application. Hold Option while opening
+EXHALE.app to change backends, repair the installation, or remove the private
+runtime. Settings offers daily update checks and Update now, which preserves
+the backends and validates a new runtime before switching to it. To update the
+launcher/setup tools, quit EXHALE and replace the app with a newer release; setup
+will install its bundled release with your previous backend choices. For removal, use
+**Remove Runtime** in setup, then move EXHALE.app to Trash. Projects, model files,
+and application settings are retained.
+
+Alternatively, use the same uv installation, backend selection and update
+commands as on Linux. Start the application with `exhale`. The desktop/menu
+registration commands are Linux-only; to uninstall a Mac uv installation, run:
+
+```bash
+uv tool uninstall exhale-xrf
+```
+
+App-managed environments are separate from installations made with
+`uv tool install`.
+
+### pip and source installations
+
+Use a virtual environment with a supported Python version (3.11–3.13).
+**Windows StarDist requires Python 3.11** because of its TensorFlow dependency.
+
+For StarDist:
+
+```bash
+python -m pip install 'exhale-xrf[stardist]'
+```
+
+For Cellpose and MONAI U-Net (Apple Silicon required on macOS):
+
+```bash
+python -m pip install 'exhale-xrf[cellpose,monai]' -r https://raw.githubusercontent.com/ctroein/exhale/main/requirements-cellpose.txt
+```
+
+For MONAI U-Net alone, use `python -m pip install 'exhale-xrf[monai]'`; no
+DINOv3 requirements file is needed. Use `'exhale-xrf[stardist,cellpose,monai]'` with
+the same requirements argument to include all three methods. For a Git checkout:
+
+```bash
+python -m pip install -e '.[stardist,cellpose,monai]' -r requirements-cellpose.txt
+./run_exhale.py
+```
+
+Omit unwanted extras and the requirements file when Cellpose is not needed.
+On Windows, launch the checkout with `python run_exhale.py`.
+
+### DINOv3 and trained models
+
+The additional requirements file pins DINOv3 to a tested source archive; Git is
+not required. For a particular EXHALE release, replace `main` in the requirements
+URL with its `vVERSION` tag and append `==VERSION` to the package specification.
+A version-pinned uv installation must be reinstalled with a newer version
+specification to upgrade.
+
+Trained Cellpose weights are downloaded on first use to the model directory in
+application settings. The same mechanism is used for installed applications and
+Git checkouts; the large weights are not included in the application installer.
+DINOv3 code and derived model weights retain the
+[DINOv3 license](exhale/resources/licenses/DINOv3-LICENSE.md).
+
+## Developer documentation
+
+Developer documentation is located in [`docs/`](docs/README.md).

exhale_xrf-1.5.0/README.md

@@ -0,0 +1,189 @@
+# Exhale
+## Efficient X-ray Hub Aiding Lung Explorations
+
+<p align="center">
+  <img src="artwork/screenshots/segmentation_20261023.png"
+       alt="EXHALE segmentation results"
+       width="900">
+</p>
+
+This project aims to develop a specialized tool for investigating elemental aspects of chronic lung diseases. 
+
+From the [VINNOVA project
+description](https://www.vinnova.se/en/p/exhale--efficient-x-ray-hub-aiding-lung-explorations/):  
+The purpose of this project is to advance understanding and treatment of
+chronic lung diseases, leading causes of mortality worldwide, by
+characterizing elements in lung tissue suspected to impact their
+pathogenesis. The industrial partners TrulyLabs and AnaMar in collaboration
+with MAX IV, Lung Biology and Correlative Image Processing and Analysis
+(CIPA) fom Lund University, aim to streamline a workflow of X-ray imaging
+studies for lung diseases, making these methods more accessible for
+biomedical companies and clinical researchers.
+
+## Currect functionality
+
+* Loading HDF5 files with XRF data from the NanoMAX beamline at MAX IV.
+* Composing element maps into publication-ready figures.
+* Segmentation of cells and clustering of areas in element maps.
+
+## Installation
+
+### Linux
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) if needed,
+then choose the segmentation backends you want.
+
+For StarDist (TensorFlow):
+
+```bash
+uv tool install --python 3.12 'exhale-xrf[stardist]'
+```
+
+For Cellpose and MONAI U-Net (PyTorch; Cellpose also needs DINOv3):
+
+```bash
+uv tool install --python 3.12 --with-requirements https://raw.githubusercontent.com/ctroein/exhale/main/requirements-cellpose.txt 'exhale-xrf[cellpose,monai]'
+```
+
+For MONAI U-Net alone:
+
+```bash
+uv tool install --python 3.12 'exhale-xrf[monai]'
+```
+
+MONAI U-Net's trained weights are bundled; no model download is needed.
+
+To also include StarDist, use `'exhale-xrf[stardist,cellpose,monai]'` with the same additional
+requirements argument. Plain `exhale-xrf` installs viewing, composition and
+analysis of existing results without neural segmentation backends. Unavailable
+backends are disabled in the application.
+
+Run `exhale` to start the application. To add it to the current user's desktop
+environment and application menu:
+
+```bash
+exhale --install-desktop
+```
+
+To update the application and its selected backends:
+
+```bash
+uv tool upgrade exhale-xrf
+```
+
+On Linux, Settings also offers daily update checks and a Check now button.
+Checks notify you of newer stable releases without installing anything. For a
+writable uv tool installation owned by your account, Update now closes Exhale,
+runs the upgrade, checks startup, and reopens it. Normal project saving applies
+before closing. Other Exhale instances must be closed first. Update results and
+the log location are shown after restarting. Automatic checks can be disabled
+in Settings.
+
+uv retains the installation settings, including extras and additional
+requirements. To change backend selection, rerun `uv tool install` with the
+wanted extras and, for Cellpose, the requirements argument.
+
+To uninstall, remove the desktop/menu entry before removing the application:
+
+```bash
+exhale --remove-desktop
+uv tool uninstall exhale-xrf
+```
+
+### Windows
+
+Windows 10 or later with 64-bit compatibility is required. Download the
+`exhale-…-setup.exe` installer from the
+[GitHub releases page](https://github.com/ctroein/exhale/releases) and run it.
+
+The installer offers StarDist, Cellpose, both, or neither before setup. It
+downloads a private Python environment and the selected packages; internet
+access is required, but an existing Python or uv installation is not.
+Use the Start menu or optional desktop shortcut to launch EXHALE.
+
+Settings offers daily update checks, Check now, and Update now. Application
+updates preserve the selected backends and validate a new runtime before
+switching to it. You can also download and run a newer installer; use that to
+update the launcher/setup tools, change backends, or repair the installation.
+Uninstall through Windows Settings; the private runtime and shortcuts are
+removed while projects, trained models and application settings are retained.
+
+### macOS
+
+Download the Apple Silicon (`arm64`) or Intel (`x86_64`) DMG from the
+[GitHub releases page](https://github.com/ctroein/exhale/releases), drag
+EXHALE.app into Applications, and open it there. Setup downloads Python and the
+selected segmentation backends; neither Python nor uv needs to be installed
+beforehand. Intel Macs support StarDist but not the current Cellpose backend.
+The launcher requires macOS 13 or newer; Cellpose's PyTorch requires at least
+macOS 14 on Apple Silicon, and dependencies may require newer versions.
+
+The Mac app is not Developer ID signed or notarized. macOS may block its first
+launch; see [Apple's explanation and opening options](https://support.apple.com/102445).
+
+Subsequent launches open the installed application. Hold Option while opening
+EXHALE.app to change backends, repair the installation, or remove the private
+runtime. Settings offers daily update checks and Update now, which preserves
+the backends and validates a new runtime before switching to it. To update the
+launcher/setup tools, quit EXHALE and replace the app with a newer release; setup
+will install its bundled release with your previous backend choices. For removal, use
+**Remove Runtime** in setup, then move EXHALE.app to Trash. Projects, model files,
+and application settings are retained.
+
+Alternatively, use the same uv installation, backend selection and update
+commands as on Linux. Start the application with `exhale`. The desktop/menu
+registration commands are Linux-only; to uninstall a Mac uv installation, run:
+
+```bash
+uv tool uninstall exhale-xrf
+```
+
+App-managed environments are separate from installations made with
+`uv tool install`.
+
+### pip and source installations
+
+Use a virtual environment with a supported Python version (3.11–3.13).
+**Windows StarDist requires Python 3.11** because of its TensorFlow dependency.
+
+For StarDist:
+
+```bash
+python -m pip install 'exhale-xrf[stardist]'
+```
+
+For Cellpose and MONAI U-Net (Apple Silicon required on macOS):
+
+```bash
+python -m pip install 'exhale-xrf[cellpose,monai]' -r https://raw.githubusercontent.com/ctroein/exhale/main/requirements-cellpose.txt
+```
+
+For MONAI U-Net alone, use `python -m pip install 'exhale-xrf[monai]'`; no
+DINOv3 requirements file is needed. Use `'exhale-xrf[stardist,cellpose,monai]'` with
+the same requirements argument to include all three methods. For a Git checkout:
+
+```bash
+python -m pip install -e '.[stardist,cellpose,monai]' -r requirements-cellpose.txt
+./run_exhale.py
+```
+
+Omit unwanted extras and the requirements file when Cellpose is not needed.
+On Windows, launch the checkout with `python run_exhale.py`.
+
+### DINOv3 and trained models
+
+The additional requirements file pins DINOv3 to a tested source archive; Git is
+not required. For a particular EXHALE release, replace `main` in the requirements
+URL with its `vVERSION` tag and append `==VERSION` to the package specification.
+A version-pinned uv installation must be reinstalled with a newer version
+specification to upgrade.
+
+Trained Cellpose weights are downloaded on first use to the model directory in
+application settings. The same mechanism is used for installed applications and
+Git checkouts; the large weights are not included in the application installer.
+DINOv3 code and derived model weights retain the
+[DINOv3 license](exhale/resources/licenses/DINOv3-LICENSE.md).
+
+## Developer documentation
+
+Developer documentation is located in [`docs/`](docs/README.md).

exhale_xrf-1.5.0/artwork/generate/extract_xrf_icon.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""Extract the generated X artwork into reproducible icon-source variants."""
+
+from argparse import ArgumentParser
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+from scipy.ndimage import distance_transform_edt, label
+
+HERE = Path(__file__).resolve().parent
+ROOT = HERE.parents[1]
+
+SOURCE_X_RECT = (11, 6, 20, 20)  # Inclusive x1, y1, x2, y2 in the 57-pixel mask.
+GUIDE_RG_COLORS = ((230, 35, 0), (0, 190, 0), (218, 151, 18))
+DARK_GREEN = (7, 31, 16)
+RUNTIME_ICON = ROOT / "exhale" / "resources" / "icons" / "xrf.png"
+
+
+def source_x_mask(source: np.ndarray) -> np.ndarray:
+    """Return red-or-green X pixels from its clean source rectangle."""
+    red_or_green = (source & 0b011) != 0
+    x1, y1, x2, y2 = SOURCE_X_RECT
+    mask = np.zeros_like(red_or_green)
+    mask[y1 : y2 + 1, x1 : x2 + 1] = red_or_green[y1 : y2 + 1, x1 : x2 + 1]
+    if not mask.any():
+        raise ValueError(f"no source X pixels found in {SOURCE_X_RECT}")
+    return mask
+
+
+def fitted_x_mask(source: np.ndarray, guide: np.ndarray) -> np.ndarray:
+    """Match the source X to its fitted red, green, and yellow guide components."""
+    source_mask = source_x_mask(source)
+    if guide.shape[0] != guide.shape[1] or source.shape[0] != source.shape[1]:
+        raise ValueError("source mask and guide must be square")
+    scaled_source = (
+        np.asarray(
+            Image.fromarray(source_mask.astype(np.uint8) * 255).resize(
+                (guide.shape[1], guide.shape[0]),
+                Image.Resampling.NEAREST,
+            )
+        )
+        != 0
+    )
+
+    candidate = np.zeros(guide.shape[:2], dtype=bool)
+    for color in GUIDE_RG_COLORS:
+        candidate |= np.all(guide == color, axis=2)
+    components, _ = label(candidate, structure=np.ones((3, 3), dtype=np.uint8))
+    component_ids = np.unique(components[scaled_source & candidate])
+    component_ids = component_ids[component_ids != 0]
+    if not len(component_ids):
+        raise ValueError("no fitted guide components overlap the source X")
+    return np.isin(components, component_ids)
+
+
+def expanded_masks(mask: np.ndarray, margin: float, feather: float) -> tuple[np.ndarray, ...]:
+    """Return round-cornered core and outer masks plus the exterior blend weight."""
+    if margin < 0 or feather < 0:
+        raise ValueError("margin and feather must not be negative")
+    distance = distance_transform_edt(~mask)
+    core = distance <= margin
+    outer = distance <= margin + feather
+    blend = np.clip((margin + feather - distance) / max(feather, 1.0), 0.0, 1.0)
+    blend[core] = 1.0
+    blend = blend * blend * (3.0 - 2.0 * blend)
+    return core, outer, blend
+
+
+def square_crop_bounds(mask: np.ndarray, size: int) -> tuple[int, int, int, int]:
+    """Return a centered fixed-size crop around the mask."""
+    rows, columns = np.nonzero(mask)
+    if not len(rows):
+        raise ValueError("cannot crop an empty mask")
+    center_x = int(columns.min() + columns.max() + 1) // 2
+    center_y = int(rows.min() + rows.max() + 1) // 2
+    left = center_x - size // 2
+    upper = center_y - size // 2
+    if left < 0 or upper < 0 or left + size > mask.shape[1] or upper + size > mask.shape[0]:
+        raise ValueError("the centered icon crop extends beyond the image")
+    return left, upper, left + size, upper + size
+
+
+def extract_icon_sources(
+    source_path: Path,
+    guide_path: Path,
+    image_path: Path,
+    output_directory: Path,
+    crop_size: int = 360,
+    margin: float = 12.0,
+    feather: float = 4.0,
+    install_runtime: bool = False,
+) -> tuple[Path, ...]:
+    """Write the mask, diagnostic, transparent, and opaque icon sources."""
+    with Image.open(source_path) as image:
+        source = np.asarray(image).copy()
+    with Image.open(guide_path) as image:
+        guide = np.asarray(image.convert("RGB"))
+    with Image.open(image_path) as image:
+        generated = np.asarray(image.convert("RGB"))
+    if generated.shape != guide.shape:
+        raise ValueError("guide and generated image dimensions differ")
+
+    fitted_mask = fitted_x_mask(source, guide)
+    core_mask, _outer_mask, blend = expanded_masks(fitted_mask, margin, feather)
+    bounds = square_crop_bounds(core_mask, crop_size)
+    left, upper, right, lower = bounds
+    cropped_mask = core_mask[upper:lower, left:right].copy()
+    cropped_mask[[0, -1], :] = False
+    cropped_mask[:, [0, -1]] = False
+    cropped_blend = blend[upper:lower, left:right, None]
+    cropped_image = generated[upper:lower, left:right]
+
+    output_directory.mkdir(parents=True, exist_ok=True)
+    mask_path = output_directory / "xrf_icon_x_mask.png"
+    diagnostic_path = output_directory / "xrf_icon_x_region.png"
+    transparent_path = output_directory / "xrf_icon_x_transparent.png"
+    dark_path = output_directory / "xrf_icon_x_dark.png"
+
+    Image.fromarray(cropped_mask.astype(np.uint8) * 255, "L").save(mask_path)
+
+    dark_color = np.asarray(DARK_GREEN, dtype=np.float32)
+    composited = np.round(
+        cropped_image.astype(np.float32) * cropped_blend + dark_color * (1.0 - cropped_blend)
+    ).astype(np.uint8)
+
+    luminance = np.clip(
+        0.2126 * cropped_image[..., 0]
+        + 0.7152 * cropped_image[..., 1]
+        + 0.0722 * cropped_image[..., 2],
+        0,
+        255,
+    ).astype(np.uint8)
+    diagnostic = np.repeat(luminance[..., None], 3, axis=2)
+    diagnostic[cropped_mask] = composited[cropped_mask]
+    Image.fromarray(diagnostic, "RGB").save(diagnostic_path)
+
+    transparent = np.empty((*cropped_mask.shape, 4), dtype=np.uint8)
+    transparent[..., :3] = composited
+    transparent[..., 3] = cropped_mask.astype(np.uint8) * 255
+    Image.fromarray(transparent, "RGBA").save(transparent_path)
+
+    dark = np.empty_like(composited)
+    dark[:] = DARK_GREEN
+    dark[cropped_mask] = composited[cropped_mask]
+    Image.fromarray(dark, "RGB").save(dark_path)
+
+    if install_runtime:
+        RUNTIME_ICON.parent.mkdir(parents=True, exist_ok=True)
+        with Image.open(transparent_path) as image:
+            image.resize((512, 512), Image.Resampling.LANCZOS).save(RUNTIME_ICON)
+
+    return mask_path, diagnostic_path, transparent_path, dark_path
+
+
+def parse_args() -> ArgumentParser:
+    parser = ArgumentParser(description=__doc__)
+    parser.add_argument("--source", type=Path, default=HERE / "57-masks.png")
+    parser.add_argument("--guide", type=Path, default=HERE / "xrf_guide_57.png")
+    parser.add_argument("--image", type=Path, default=HERE / "xrf_imagegen_57.png")
+    parser.add_argument("--output-directory", type=Path, default=HERE)
+    parser.add_argument("--crop-size", type=int, default=360)
+    parser.add_argument("--margin", type=float, default=12.0)
+    parser.add_argument("--feather", type=float, default=4.0)
+    parser.add_argument(
+        "--install-runtime",
+        action="store_true",
+        help="install the transparent 512-pixel application and Linux icon",
+    )
+    return parser
+
+
+def main() -> None:
+    args = parse_args().parse_args()
+    paths = extract_icon_sources(
+        args.source,
+        args.guide,
+        args.image,
+        args.output_directory,
+        args.crop_size,
+        args.margin,
+        args.feather,
+        args.install_runtime,
+    )
+    for path in paths:
+        print(path)
+
+
+if __name__ == "__main__":
+    main()