[BUG] GUI stitching fails for Blaze datasets (KeyError: 'Z' in Preview, ValueError: Z not in tile_axes=['X','Y'] in Run Stitching)

[RedTabby01]

Operating System

Windows

OS Version

Windows11

Code Version

ClearMap2 release: 2.1.4

How are you using the application?

GUI

Expected Behavior

Preview Overlap should display the overlap image, and Run Stitching should initialize WobblyLayout without raising an exception.

Actual Behavior

Preview Overlap fails with KeyError: 'Z' and
Run Stitching fails with ValueError: The expression has the named pattern Z that is not in tile_axes=['X','Y'] when processing Blaze datasets.

Steps to Reproduce

Create a project from Blaze microscope data (3×2 mosaic).
Run Input Conversion.
Click Preview Overlap → KeyError: 'Z'.
Click Run Stitching → ValueError: ... tile_axes=['X','Y'].

ClearMap2 2.1.4 Ubuntu 20.04 (WSL2) Python 3.9

Logs and Screenshots

Hello,

First of all, thank you very much for developing and maintaining ClearMap2.

I encountered two reproducible issues while processing Blaze microscope data using the GUI. After tracing the code and performing several debugging steps, I believe they may be related to how the Z dimension is handled during stitching.

## Environment

- ClearMap2 release: 2.1.4
- `ClearMap.__version__` reports `2.0.0`
- Ubuntu 20.04 (WSL2)
- Python 3.9
- GUI launched with:


python -m ClearMap.gui.run_gui


## Dataset

Microscope: Blaze

Mosaic:

- 3 × 2 tiles

The images were acquired with **10% overlap** in both X and Y directions.

Input conversion successfully converted all TIFF files:


Converting 10032 files to npy: elapsed time: 0:06:59.835


Therefore, the dataset appears to have been converted successfully before stitching.

---

# Issue 1: Preview Overlap

Clicking **Preview Overlap** consistently produces


Traceback (most recent call last):
  File ".../gui/tabs.py", line 417, in preview_stitching_dumb
    overlay = [pg.image(self.preprocessor.stitch_overlay('raw', color))]
  File ".../processors/sample_preparation.py", line 762, in stitch_overlay
    middle_z = int(tile_shape['Z'] / 2)
KeyError: 'Z'


The preview therefore cannot be displayed.

---

# Issue 2: Run Stitching

Clicking **Run Stitching** consistently produces


Traceback (most recent call last):
  File ".../gui/tabs.py", line 459, in run_stitching
    self.wrap_step(...)
  ...
  File ".../processors/sample_preparation.py", line 422, in get_wobbly_layout
    layout = stitching_wobbly.WobblyLayout(
        expression=raw_path,
        tile_axes=['X','Y'],
        overlaps=overlaps
    )
  ...
  File ".../Alignment/Stitching/StitchingRigid.py", line 2250
    raise ValueError(...)
ValueError:
The expression has the named pattern Z that is not in tile_axes=['X','Y']


---

## Debugging performed

### 1. Verified the expression passed to WobblyLayout

I modified `sample_preparation.py` to inspect `raw_path`.

The expression passed to `WobblyLayout` is


.../sample_Blaze[<Y,2> x <X,2>]_C01_xyz-Table Z<Z,4>.ome.npy


Using


from ClearMap.IO.Workspace import Expression

exp = Expression(raw_path)

print(exp.tag_names())


returns


['Y', 'X', 'Z']


Therefore the expression itself correctly contains the Z tag.

---

### 2. Overlap values

My acquisition used **10% overlap**.

The GUI automatically displays


X overlap = 10 px
Y overlap = 10 px


I also manually changed the overlap values to approximately 10% in pixels (~205 px for 2048-pixel images), but both errors remained unchanged.

Therefore the overlap values do not appear to be the cause of either error.

---

## Questions

1. Is Blaze data currently supported by the GUI stitching pipeline?

2. During Preview Overlap, should `tile_shape` contain a Z dimension? Currently `stitch_overlay()` attempts to access


tile_shape['Z']


which raises `KeyError`.

3. During Run Stitching, should `WobblyLayout` accept an expression containing the Z tag, or should `get_wobbly_layout()` provide an expression without Z?

4. Regarding overlap values:
   the GUI displays them as **px**, whereas the microscope acquisition uses **percent overlap**.
   Are these values internally interpreted as percentages or pixels?

---

This behavior is reproducible on my dataset.

I'd be happy to test any suggested fixes or provide additional information.

Thank you very much for your help!