PtychographyAlignment

The applications directory contains Jupyter notebooks to analyse experimental data provided by Diamond. alignment_pipeline.ipynb is an example of the most recent alignment pipeline using CrossCorrelationAlignment, VerticalAlignment and TomoConsistencyAlignment

The src contains the core code for the package. In particular, the code is structured as follows:

• alignment contains the alignment methods. The most recent code is in the classes CrossCorrelationAlignment, VerticalAlignment and TomoConsistencyAlignment
• config contains configurations settings for the code, such as the data filepaths.
• io_module loading tools
• pipeline contains work in progress pipelines
• quality_metrics contains tools to analyse reconstruction quality
• recipe contains environment file
• simulations contains tools to simulate tomographic projections with gVXR, where each projections is shifted along the "x" and "y" axes, i.e., in the transverse plane to the x-rays propagation direction.
• utilities
  • display_tools: visualise data and plot alignment
  • phase_tools: phase unwrapping and gradient methods, sinogram ramp tools etc
  • quality_metrics: contains tools to analyse reconstruction quality
  • recon_tools: astra reconstruction and re-projection
  • shift_tools: apply shifts to projections
  • sino_tools: tools for processing sinograms, smoothing edges
  • utils_tomo and utils_used: contain wip tools used in validating_methods
• validating_methods contains work in progress methods validation
• viewer contains code to interactively view data using the CIL viewer

The tests folder contains (some) tests of the methods developed, whereby helpers contains small utility functions or classes for tests. As of 31/08/2026, the tests are likely to fail - this needs to be looked at and fixed. We recommend using an example dataset which is well-understood in order to test the pipeline (e.g. the example dataset in 10.5281/zenodo.3539550).

Note: Frequently used data can be saved in paths and user_paths to be called in multiple places. The converters directory contains scripts to convert the data/files between different formats.

Installation

Develop code locally by cloning the source code, creating a development environment and installing it.

1. Install miniconda, then launch the Miniconda Prompt.

2. Clone the main branch of PtychographyAlignment locally, and navigate into where it has been cloned:

git clone [email protected]:TomographicImaging/PtychographyAlignment.git
cd PtychographyAlignment

3. The environment file contains the dependencies needed to run the package. Create the conda environment using the following command:

conda env create -f recipe/environment.yml

4. Activate the environment:

conda activate ptychotomo_env

5. Install the package:

pip install .

or

Install the package locally allowing edits:

pip install -e .

Testing

6. Tests require the data "pollen", please store this as specified in paths. To run tests:

pytest

Test can run with visualisation outputs from the ccpi-viewer and matplotlib:

pytest --view

Conventions

For the docstrings, please use the numpydoc convention.

Example:

"""
Summarize the function in one line.

Several sentences providing an extended description. Refer to
variables using back-ticks, e.g. `var`.

Parameters
----------
var1 : array_like
    Array_like means all those objects -- lists, nested lists, etc. --
    that can be converted to an array.  We can also refer to
    variables like `var1`.
var2 : int
    The type above can either refer to an actual Python type
    (e.g. ``int``), or describe the type of the variable in more
    detail, e.g. ``(N,) ndarray`` or ``array_like``.
*args : iterable
    Other arguments.
long_var_name : {'hi', 'ho'}, optional
    Choices in brackets, default first when optional.

Returns
-------
type
    Explanation of anonymous return value of type ``type``.
describe : type
    Explanation of return value named `describe`.
out : type
    Explanation of `out`.
type_without_description
"""

Acknowledgement

This package is a modified and translated version of code from the “cSAXS matlab package” https://zenodo.org/records/3539550 developed by the CXS group https://www.psi.ch/en/sls/csaxs/software, at the Paul Scherrer Institute (PSI), Switzerland.

Original work: Copyright (c) 2017 Paul Scherrer Institute (http://www.psi.ch) Author: CXS group, PSI

Licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0).

This version: Copyright 2026 United Kingdom Research and Innovation (UKRI) and Diamond Light Source Modifications: Translated to Python, adapted and extended.

This work is distributed under the same license as the original. You may not use this work for commercial purposes. You must give appropriate credit and indicate if changes were made.

For publications using this software, please acknowledge: "This work uses a translated and adapted version of the 'cSAXS tomo package' developed by the CXS group, Paul Scherrer Institut, Switzerland." and cite M. Odstrcil, M. Holler, J. Holler, M. Guizar-Sicairos,"Alignment methods for nanotomography with deep sub-pixel accuracy", Opt. Express, (2019).

Full license text: https://creativecommons.org/licenses/by-nc-sa/4.0/