Dataset example

[bpavie]

Dear All,

Would it be possible to have an example with some data to understand exactly how to name the files to stitch them ?
An example is often easier to understand, it could be stored on zenodo for example

Right now, I am not sure how I should rename my files in order to stitch them.

E.g., let say I have a a set of 5Z, 2X and 3 Y and each tile is 1024x2048, how should the files be named ? The documentation say X_Y.tiff

Would something like this work ?

0_0.tiff
0_1024.tiff
2048_0.tiff
2048_1024.tiff
4096_0.tiff
4096_1024.tiff
6144_0.tiff
6144_1024.tiff

Where each file contains all the Z (so here, Z=5)

Would it be correct ?

Then which command should I run given that I already know there is a 15% overlapping between the tiles ?

Best,
benjamin

[gmazzamuto]

Hi, thanks for your interest in ZetaStitcher!

First of all I would like to ask you to use the version from the devel branch, as this contains some fixes that are not published yet.

Yes, your file names are correct. You should be able to perform the stitching like this:

stitch-align -e --overlap-h 300 --overlap-v 150 --dx 50 --dy 50 --dz 0 .

Followed by

stitch-fuse -o fused.tiff .

Let me know if this works!

[bpavie]

Thanks, I will try this

Are you planning to publish a new release as pip package ?

[bpavie]

Hi @gmazzamuto

I splitted my files, installed zetastitcher in a new environement and ran the command, but I got an error

What I did:

Environment installation:

• Clone the github repository

git clone -b devel https://github.com/lens-biophotonics/ZetaStitcher.git

• Create the conda environment

conda create --name zetastitcher -c conda-forge python=3.11
conda activate zetastitcher
cd ZetaStitcher
pip install -e ./

Then I ran the alignement:

stitch-align -e --overlap-h 300 --overlap-v 150 --dx 50 --dy 50 --dz 0 .

And I get the following output:

INFO [zetastitcher.align.filematrix]: adding .\0_0.ome.tiff     X=0 Y=0.0 Z=0
INFO [zetastitcher.align.filematrix]: adding .\0_2396.ome.tiff  X=0 Y=2396.0 Z=0
INFO [zetastitcher.align.filematrix]: adding .\11980_0.ome.tiff         X=11980 Y=0.0 Z=0
INFO [zetastitcher.align.filematrix]: adding .\11980_2396.ome.tiff      X=11980 Y=2396.0 Z=0
INFO [zetastitcher.align.filematrix]: adding .\2396_0.ome.tiff  X=2396 Y=0.0 Z=0
INFO [zetastitcher.align.filematrix]: adding .\2396_2396.ome.tiff       X=2396 Y=2396.0 Z=0
INFO [zetastitcher.align.filematrix]: adding .\4792_0.ome.tiff  X=4792 Y=0.0 Z=0
INFO [zetastitcher.align.filematrix]: adding .\4792_2396.ome.tiff       X=4792 Y=2396.0 Z=0
INFO [zetastitcher.align.filematrix]: adding .\7188_0.ome.tiff  X=7188 Y=0.0 Z=0
INFO [zetastitcher.align.filematrix]: adding .\7188_2396.ome.tiff       X=7188 Y=2396.0 Z=0
INFO [zetastitcher.align.filematrix]: adding .\9584_0.ome.tiff  X=9584 Y=0.0 Z=0
INFO [zetastitcher.align.filematrix]: adding .\9584_2396.ome.tiff       X=9584 Y=2396.0 Z=0
INFO [zetastitcher.align.__main__]: 6%  .\0_0.ome.tiff  .\2396_0.ome.tiff       60      [np.int64(0), np.int64(0), np.int64(61)]        0.289
INFO [zetastitcher.align.__main__]: 12% .\2396_0.ome.tiff       .\4792_0.ome.tiff       60      [np.int64(0), np.int64(0), np.int64(50)]        0.439
INFO [zetastitcher.align.__main__]: 19% .\4792_0.ome.tiff       .\7188_0.ome.tiff       60      [np.int64(0), np.int64(0), np.int64(50)]        0.140
INFO [zetastitcher.align.__main__]: 25% .\7188_0.ome.tiff       .\9584_0.ome.tiff       60      [np.int64(0), np.int64(0), np.int64(76)]        0.042
INFO [zetastitcher.align.__main__]: 31% .\9584_0.ome.tiff       .\11980_0.ome.tiff      60      [np.int64(0), np.int64(45), np.int64(15)]       0.040
INFO [zetastitcher.align.__main__]: 38% .\0_2396.ome.tiff       .\2396_2396.ome.tiff    60      [np.int64(0), np.int64(0), np.int64(51)]        0.230
INFO [zetastitcher.align.__main__]: 44% .\2396_2396.ome.tiff    .\4792_2396.ome.tiff    60      [np.int64(0), np.int64(0), np.int64(62)]        0.469
INFO [zetastitcher.align.__main__]: 50% .\4792_2396.ome.tiff    .\7188_2396.ome.tiff    60      [np.int64(0), np.int64(0), np.int64(50)]        0.758
INFO [zetastitcher.align.__main__]: 56% .\7188_2396.ome.tiff    .\9584_2396.ome.tiff    60      [np.int64(0), np.int64(0), np.int64(48)]        0.658
INFO [zetastitcher.align.__main__]: 62% .\9584_2396.ome.tiff    .\11980_2396.ome.tiff   60      [np.int64(0), np.int64(82), np.int64(81)]       0.055
INFO [zetastitcher.align.__main__]: 69% .\0_0.ome.tiff  .\0_2396.ome.tiff       60      [np.int64(0), np.int64(89), np.int64(48)]       0.029
INFO [zetastitcher.align.__main__]: 75% .\2396_0.ome.tiff       .\2396_2396.ome.tiff    60      [np.int64(0), np.int64(87), np.int64(0)]        0.075
INFO [zetastitcher.align.__main__]: 81% .\4792_0.ome.tiff       .\4792_2396.ome.tiff    60      [np.int64(0), np.int64(13), np.int64(22)]       0.069
INFO [zetastitcher.align.__main__]: 88% .\7188_0.ome.tiff       .\7188_2396.ome.tiff    60      [np.int64(0), np.int64(27), np.int64(49)]       0.079
INFO [zetastitcher.align.__main__]: 94% .\9584_0.ome.tiff       .\9584_2396.ome.tiff    60      [np.int64(0), np.int64(10), np.int64(37)]       0.054
INFO [zetastitcher.align.__main__]: 100%        .\11980_0.ome.tiff      .\11980_2396.ome.tiff   60      [np.int64(0), np.int64(43), np.int64(46)]       0.093
INFO [zetastitcher.fuse.absolute_positions]: performing global optimization...
Traceback (most recent call last):
  File "C:\Users\uxxxxxx\.conda\envs\zetastitcher\Lib\site-packages\qpsolvers\solve_problem.py", line 81, in solve_problem
    return solve_function[solver](problem, **kwargs)
           ~~~~~~~~~~~~~~^^^^^^^^
KeyError: 'cvxpy'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "C:\Users\uxxxxxx\.conda\envs\zetastitcher\Scripts\stitch-align.exe\__main__.py", line 6, in <module>
  File "C:\Users\uxxxxxx\Documents\PROJECTS\Leuven\Nikky\2025_11_Stitching\ZetaStitcher\zetastitcher\align\__main__.py", line 392, in main
    r.run()
  File "C:\Users\uxxxxxx\Documents\PROJECTS\Leuven\Nikky\2025_11_Stitching\ZetaStitcher\zetastitcher\align\__main__.py", line 347, in run
    absolute_positions.global_optimization(self.fm.data_frame, xcorr_fm)
  File "C:\Users\uxxxxxx\Documents\PROJECTS\Leuven\Nikky\2025_11_Stitching\ZetaStitcher\zetastitcher\fuse\absolute_positions.py", line 62, in global_optimization
    node2coordinates, digraph = stitcher.stitch(data_in, v_origin)
                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\uxxxxxx\Documents\PROJECTS\Leuven\Nikky\2025_11_Stitching\ZetaStitcher\zetastitcher\gaussian_stitcher\qp\stitching.py", line 100, in stitch
    x, variables = self._optimize(digraph, v_origin)
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\uxxxxxx\Documents\PROJECTS\Leuven\Nikky\2025_11_Stitching\ZetaStitcher\zetastitcher\gaussian_stitcher\qp\stitching.py", line 162, in _optimize
    x = solve_qp(P, q, G, h, A, b, solver=self.solver)
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\uxxxxxx\.conda\envs\zetastitcher\Lib\site-packages\qpsolvers\solve_qp.py", line 135, in solve_qp
    solution = solve_problem(problem, solver, initvals, verbose, **kwargs)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\uxxxxxx\.conda\envs\zetastitcher\Lib\site-packages\qpsolvers\solve_problem.py", line 83, in solve_problem
    raise SolverNotFound(
qpsolvers.exceptions.SolverNotFound: found solvers ['clarabel', 'osqp', 'scs'] but 'cvxpy' is not one of them; if 'cvxpy' is listed in https://github.com/qpsolvers/qpsolvers#solvers you can run ``pip install qpsolvers[cvxpy]``

I also followed the suggestion:

pip install qpsolvers[cvxpy]

But it's already installed

python

import qpsolvers
print(qpsolvers.available_solvers)
['clarabel', 'osqp', 'scs']

And I can import cvxpy

python -c "import cvxpy"

Requirement already satisfied: qpsolvers[cvxpy] in c:\users\uxxxxxx\.conda\envs\zetastitcher\lib\site-packages (4.8.1)
WARNING: qpsolvers 4.8.1 does not provide the extra 'cvxpy'
Requirement already satisfied: numpy>=1.15.4 in c:\users\uxxxxxx\.conda\envs\zetastitcher\lib\site-packages (from qpsolvers[cvxpy]) (2.2.6)
Requirement already satisfied: scipy>=1.2.0 in c:\users\uxxxxxx\.conda\envs\zetastitcher\lib\site-packages (from qpsolvers[cvxpy]) (1.16.3)

If you have any tips, or need the images to test this, let me know

Best,
Benjamin

[bpavie]

To add one th image format:

from bioio import BioImage
import bioio_ome_tiff


output_file_path = '..\\split_images\\0_0.ome.tiff'

img = BioImage(output_file_path, reader=bioio_ome_tiff.Reader)
print(img.dims)  # returns a Dimensions object
print(img.dims.order)  # returns string "TCZYX"
print(img.dims.X)  # returns size of X dimension
print(img.shape)  # returns tuple of dimension sizes in TCZYX order

<Dimensions [T: 1, C: 1, Z: 121, Y: 2396, X: 2396]>
TCZYX
2396
(1, 1, 121, 2396, 2396)

[gmazzamuto]

Unfortunately cvxpy was removed from qpsolvers long ago. I have switched to a different solver and pushed the new changes to the develop branch. Can you please try again?

Please note though that I have never tried ZetaStitcher on Windows. I hope it works for you, let me know how it goes!

[bpavie]

Hi @gmazzamuto

Thanks for the quick answer, I re-clone the develop branch and reinstall a conda environement, but now get another error:

(...)
INFO [zetastitcher.align.__main__]: 100%        .\11980_0.ome.tiff      .\11980_2396.ome.tiff   60      [np.int64(0), np.int64(43), np.int64(46)]       0.093
INFO [zetastitcher.fuse.absolute_positions]: performing global optimization...
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "C:\Users\uxxxxxx\.conda\envs\zetastitcher\Scripts\stitch-align.exe\__main__.py", line 6, in <module>
  File "C:\Users\uxxxxxx\Documents\PROJECTS\Leuven\Nikky\2025_11_Stitching\ZetaStitcher\zetastitcher\align\__main__.py", line 392, in main
    r.run()
  File "C:\Users\uxxxxxx\Documents\PROJECTS\Leuven\Nikky\2025_11_Stitching\ZetaStitcher\zetastitcher\align\__main__.py", line 347, in run
    absolute_positions.global_optimization(self.fm.data_frame, xcorr_fm)
  File "C:\Users\uxxxxxx\Documents\PROJECTS\Leuven\Nikky\2025_11_Stitching\ZetaStitcher\zetastitcher\fuse\absolute_positions.py", line 62, in global_optimization
    node2coordinates, digraph = stitcher.stitch(data_in, v_origin)
                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\uxxxxxx\Documents\PROJECTS\Leuven\Nikky\2025_11_Stitching\ZetaStitcher\zetastitcher\gaussian_stitcher\qp\stitching.py", line 102, in stitch
    raise Exception("solver error")
Exception: solver error

Best,
Benjamin

[gmazzamuto]

This may be because the solver can't find a global optimization. Indeed, I would have liked to do more thorough testing before changing the solver, which is also the reason why I postponed it for so long.

I think we have the following options to move forward:

• you can open the file zetastitcher/fuse/absolute_positions.py and simply try with a different solver by changing line 60. You can even install new solvers among those compatible with qpsolvers, which are many. It would be interesting to know if you find a good configuration in this respect.
• If your experimental setup is good enough, you may even try nominal stitching, i.e. simply fuse the tiles at their nominal coordinates. Often this is good enough.
• If you don't mind sharing the images, I can give it a try locally on my computer.
• If you are familiar with using docker, I can provide a working docker image, that you can still invoke from the command line as shown in the README.md, where all the dependencies are in place including the old cvxpy.

Let me know your ideas!

Best,
Giacomo

[bpavie]

Hi @gmazzamuto

Having a functional docker image will be nice, if you could provide that that would be very nice !

Best
Benjamin

[gmazzamuto]

OK so I've created a temporary branch temp-docker that you can use to build the docker image by first running pip install build then following the instructions in the README.md. If you don't have make, then you need to run these commands:

pip install build
python -m build
docker build -t zetastitcher -f docker/Dockerfile dist

If for whatever reason the build process fails I can provide a link to download the docker image built by myself. Btw, if you really need to use Windows maybe it's easier to run everything, including Docker, in WSL.

Hope this works!
Giacomo