# HoloWizard
<img src="https://connect.helmholtz-imaging.de/media/solution/Holowizard_logo.png" width="200"/>
[](https://github.com/DESY-FS-PETRA/holowizard)
[](https://github.com/DESY-FS-PETRA/holowizard/blob/main/LICENSE)
[](https://pypi.org/project/holowizard/)
[](https://doi.org/10.5281/zenodo.16275927)
HoloWizard is a collection of software tools for phase retrieval in the setting of near-field holographic microscopy and tomography.
It is developed at DESY, Hamburg in the group X-Ray Nanoscience and X-Ray Optics.
The software is designed to cover all steps in experimental/algorithm development:
- The Forge generates datasets within given variation bouds either for testing new algorithms or provide training data sets for ML applications
- The Core implements the ASRM algorithm, our phase retrieval engine. It includes also all neccessary auxillary functions to load and preprocess single holograms/diffraction patterns.
- The Pipe enables the **online** and **offline** batch processing of holo tomograms, i.e. the phase retrieval of individual projections(along with all preprocessing steps) and the computation of the tomographic volume from the retrieved projections.
- The Livereco module can show online reconstructions of single projections during an experiment i.e. for finding a suited region of interest. It can be integrated in existing experimental control software.
# Table of Contents
- [Installation](#installation)
- [Python Environment](#python-environment)
- [Install package](#install-package)
- [Tools](#tools)
- [The Core](#the-core)
- [The Pipe](#the-pipe)
- [The Forge](#the-forge)
- [The Livereco](#the-livereco)
- [Citations](#citations)
- [Artifact-suppressing reconstruction method:](#artifact-suppressing-reconstruction-method)
- [Model-based autofocus:](#model-based-autofocus)
- [Further links](#further-links)
# Installation
## Python Environment
Create a new environment with python 3.11., i.e. with mamba
```bash
$ mamba create -p <path_to_env> python=3.11
```
Activate enviroment
```bash
$ mamba activate <path_to_env>
```
## Install package
```bash
$ pip install holowizard
```
# Tools
## The Core
To create examples, open a terminal and run
```{bash}
$ holowizard_core_create_examples <directory>
```
## The Pipe
### Setting Up an Instance
We provide a CLI command to initialize everything:
```bash
$ holowizard_pipe_start beamtime.name=YOUR_BEAMTIME_NAME beamtime.year=YEAR_OF_BEAMTIME
```
This command sets up the pipeline. You can override any other configuration value using Hydra’s override syntax:
👉 [Hydra Override Syntax Documentation](https://hydra.cc/docs/advanced/override_grammar/basic/)
If the startup is successful, you’ll see output like:
```
INFO: Uvicorn running on http://MY_IP_ADDRESS:MY_PORT (Press CTRL+C to quit)
```
Click the address to open a browser window showing that `holopipe` is running.
Visit: `http://MY_IP_ADDRESS:MY_PORT/dashboard` for useful runtime information.
### Add a scan with default parameters.
You can submit scans using a simple `curl` POST request:
```bash
curl -X POST \
-H "Content-Type: application/json" \
-d '{ "a0": 1.0,
"scan-name": "nano145014_s7_1_tum",
"holder": 220,
"base_dir": "holopipe",
"reconstruction": "wire",
"find_focus": "wire",
"energy": 17.0
}' \
http://MY_IP_ADDRESS:MY_PORT/api/submit_scan
```
If you are on the same machine as the server is running you can use the python script:
```bash
holowizard_pipe_reconstruct_scan --help # will tell you all important parameters
```
#### Required Parameters
- `name`: Folder name of the current scan
- `holder`: Height of the holder
- `energy`: Scan energy in keV
#### Optional Parameters
- `a0`: Optional numeric parameter; if not provided, it will be computed automatically
- `reconstruction`: Instruction set for reconstruction — `wire` (default) or `spider`
- `find_focus`: Instruction set to find focus — `wire` (default) or `spider`
- `base_dir`: Root directory for output files (default: `holopipe`)
### Parameter Optimization
To performe parameter optimization go to `http://MY_IP_ADDRESS:MY_PORT/parameter`. Here you can set all parameter for all stages. To test them click `Reconstruct`. If the parameters work well, you can save them to the current beamtime folder using the `Save as` at the lower left.
If you want to reconstruct the whole scan you can click `Submit All` after chosing the Options. If you select `Custom` it will take the parameters from the left.
### Other changes during beamtime
If you change the detector or anything else like removing tasks adapt parameters the full config files are located in the `beamtime/processed/holowizard_config/`folder. Changes here will reflect onto future curl requests!
## The Forge
This framework can be used to generate large datasets of simulated holograms of randomly sampled objects.
### Create New Dataset
Open a terminal and create a new config file with
```{bash}
$ holowziard_forge_create_testconfig <args>
```
| Argument | Description | Position |
|-----------------|-----------------------------------------------------------|----------|
| `name` | Name of the new config file (without file name extension) | 1 |
| `--output_dir` | Output directory | optional |
| `--override` | Overrides existing configuration file | optional |
The config file can then be customized and used to create a new dataset with
```{bash}
$ holowizard_forge_generate_data <args>
```
| Argument | Description | Position |
|---------------|------------------------------------------------------|----------|
| `config` | Path to the custom configuration file. | 1 |
| `output_dir` | Output directory where the generated data is stored. | 2 |
| `num_samples` | Number of data samples that should be generated. | 3 |
| `--override` | Override the output folder if it already exists. | optional |
### Output Structure
```
output/
└── train.hdf5
└── train.json
```
The file train.hdf5 contains the training data
The file `train.json` contains the config parameters which have been used for the training data creation.
### Developer Info
#### Add new Parameters
To add a new parameter, add it to the default configuration `holowizard/forge/configs/default.json`.
## The Livereco
Start the online reconstruction server with
```{bash}
$ holowizard_livereco_server_start
```
# Citations
### Artifact-suppressing reconstruction method:
- URL: https://opg.optica.org/oe/fulltext.cfm?uri=oe-32-7-10801&id=547807###
- DOI: 10.1364/OE.514641
```{bibtex}
@article{Dora:24,
author = {Johannes Dora and Martin M\"{o}ddel and Silja Flenner and Christian G. Schroer and Tobias Knopp and Johannes Hagemann},
journal = {Opt. Express},
keywords = {Free electron lasers; Holographic microscopy; Imaging techniques; Phase shift; X-ray imaging; Zone plates},
number = {7},
pages = {10801--10828},
publisher = {Optica Publishing Group},
title = {{Artifact-suppressing reconstruction of strongly interacting objects in X-ray near-field holography without a spatial support constraint}},
volume = {32},
month = {Mar},
year = {2024},
url = {https://opg.optica.org/oe/abstract.cfm?URI=oe-32-7-10801},
doi = {10.1364/OE.514641},
abstract = {The phase problem is a well known ill-posed reconstruction problem of coherent lens-less microscopic imaging, where only the squared magnitude of a complex wavefront is measured by a detector while the phase information of the wave field is lost. To retrieve the lost information, common algorithms rely either on multiple data acquisitions under varying measurement conditions or on the application of strong constraints such as a spatial support. In X-ray near-field holography, however, these methods are rendered impractical in the setting of time sensitive in situ and operando measurements. In this paper, we will forego the spatial support constraint and propose a projected gradient descent (PGD) based reconstruction scheme in combination with proper preprocessing and regularization that significantly reduces artifacts for refractive reconstructions from only a single acquired hologram without a spatial support constraint. We demonstrate the feasibility and robustness of our approach on different data sets obtained at the nano imaging endstation of P05 at PETRA III (DESY, Hamburg) operated by Helmholtz-Zentrum Hereon.},
}
```
### Model-based autofocus:
- URL: https://opg.optica.org/oe/abstract.cfm?doi=10.1364/OE.544573
- DOI: 10.1364/OE.544573
```{bibtex}
@article{Dora:25,
author = {Johannes Dora and Martin M\"{o}ddel and Silja Flenner and Jan Reimers and Berit Zeller-Plumhoff and Christian G. Schroer and Tobias Knopp and Johannes Hagemann},
journal = {Opt. Express},
keywords = {Image analysis; Image metrics; Imaging systems; Phase retrieval; X-ray imaging; Zone plates},
number = {4},
pages = {6641--6657},
publisher = {Optica Publishing Group},
title = {Model-based autofocus for near-field phase retrieval},
volume = {33},
month = {Feb},
year = {2025},
url = {https://opg.optica.org/oe/abstract.cfm?URI=oe-33-4-6641},
doi = {10.1364/OE.544573},
}
```
## Further links
https://helmholtz.software/software/holowizard \
https://connect.helmholtz-imaging.de/solution/71 \
https://connect.helmholtz-imaging.de/blog_gallery/blogpost/10
Raw data
{
"_id": null,
"home_page": null,
"name": "holowizard",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12,>=3.11",
"maintainer_email": "Johannes Dora <johannes.dora@desy.de>, Andr\u00e9 Lopes <andre.lopes@hereon.de>, Johannes Gr\u00fcn <johannes.gruen@desy.de>, Sebastian Eberle <sebastian.eberle@desy.de>, Johannes Hagemann <johannes.hagemann@desy.de>",
"keywords": "near-field holography, phase retrieval, tomography",
"author": null,
"author_email": "Johannes Dora <johannes.dora@desy.de>, Johannes Hagemann <johannes.hagemann@desy.de>, Andr\u00e9 Lopes <andre.lopes@hereon.de>, Silja Flenner <silja.flenner@hereon.de>, Johannes Gr\u00fcn <johannes.gruen@desy.de>, Sebastian Eberle <sebastian.eberle@desy.de>, Cem Cinar <cem.cinar@tuhh.de>",
"download_url": "https://files.pythonhosted.org/packages/c6/86/df0d0bdd533ad80d8d79ded67242123e5973fb6d10f05ffde33b80165a5b/holowizard-2.0.1.tar.gz",
"platform": null,
"description": "# HoloWizard\n<img src=\"https://connect.helmholtz-imaging.de/media/solution/Holowizard_logo.png\" width=\"200\"/> \n\n[](https://github.com/DESY-FS-PETRA/holowizard)\n[](https://github.com/DESY-FS-PETRA/holowizard/blob/main/LICENSE)\n\n[](https://pypi.org/project/holowizard/)\n[](https://doi.org/10.5281/zenodo.16275927)\n\nHoloWizard is a collection of software tools for phase retrieval in the setting of near-field holographic microscopy and tomography.\nIt is developed at DESY, Hamburg in the group X-Ray Nanoscience and X-Ray Optics.\nThe software is designed to cover all steps in experimental/algorithm development:\n- The Forge generates datasets within given variation bouds either for testing new algorithms or provide training data sets for ML applications\n- The Core implements the ASRM algorithm, our phase retrieval engine. It includes also all neccessary auxillary functions to load and preprocess single holograms/diffraction patterns.\n- The Pipe enables the **online** and **offline** batch processing of holo tomograms, i.e. the phase retrieval of individual projections(along with all preprocessing steps) and the computation of the tomographic volume from the retrieved projections.\n- The Livereco module can show online reconstructions of single projections during an experiment i.e. for finding a suited region of interest. It can be integrated in existing experimental control software.\n\n# Table of Contents\n- [Installation](#installation)\n - [Python Environment](#python-environment)\n - [Install package](#install-package)\n- [Tools](#tools)\n - [The Core](#the-core)\n - [The Pipe](#the-pipe)\n - [The Forge](#the-forge)\n - [The Livereco](#the-livereco)\n- [Citations](#citations)\n - [Artifact-suppressing reconstruction method:](#artifact-suppressing-reconstruction-method)\n - [Model-based autofocus:](#model-based-autofocus)\n - [Further links](#further-links)\n\n# Installation\n## Python Environment\nCreate a new environment with python 3.11., i.e. with mamba\n```bash\n$ mamba create -p <path_to_env> python=3.11 \n```\n\nActivate enviroment\n```bash\n$ mamba activate <path_to_env>\n```\n\n## Install package\n```bash\n$ pip install holowizard\n```\n\n# Tools\n\n## The Core\n\nTo create examples, open a terminal and run\n\n```{bash}\n$ holowizard_core_create_examples <directory>\n```\n\n## The Pipe\n\n### Setting Up an Instance\n\nWe provide a CLI command to initialize everything:\n\n```bash\n$ holowizard_pipe_start beamtime.name=YOUR_BEAMTIME_NAME beamtime.year=YEAR_OF_BEAMTIME\n```\n\nThis command sets up the pipeline. You can override any other configuration value using Hydra\u2019s override syntax: \n\ud83d\udc49 [Hydra Override Syntax Documentation](https://hydra.cc/docs/advanced/override_grammar/basic/)\n\nIf the startup is successful, you\u2019ll see output like:\n\n```\nINFO: Uvicorn running on http://MY_IP_ADDRESS:MY_PORT (Press CTRL+C to quit)\n```\n\nClick the address to open a browser window showing that `holopipe` is running. \nVisit: `http://MY_IP_ADDRESS:MY_PORT/dashboard` for useful runtime information.\n\n\n### Add a scan with default parameters. \n\nYou can submit scans using a simple `curl` POST request:\n\n```bash\ncurl -X POST \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"a0\": 1.0,\n \"scan-name\": \"nano145014_s7_1_tum\",\n \"holder\": 220,\n \"base_dir\": \"holopipe\",\n \"reconstruction\": \"wire\",\n \"find_focus\": \"wire\",\n \"energy\": 17.0\n }' \\\n http://MY_IP_ADDRESS:MY_PORT/api/submit_scan\n```\n\nIf you are on the same machine as the server is running you can use the python script:\n```bash\nholowizard_pipe_reconstruct_scan --help # will tell you all important parameters\n```\n\n#### Required Parameters\n\n- `name`: Folder name of the current scan \n- `holder`: Height of the holder \n- `energy`: Scan energy in keV \n\n#### Optional Parameters\n\n- `a0`: Optional numeric parameter; if not provided, it will be computed automatically \n- `reconstruction`: Instruction set for reconstruction \u2014 `wire` (default) or `spider` \n- `find_focus`: Instruction set to find focus \u2014 `wire` (default) or `spider` \n- `base_dir`: Root directory for output files (default: `holopipe`)\n\n### Parameter Optimization\n\nTo performe parameter optimization go to `http://MY_IP_ADDRESS:MY_PORT/parameter`. Here you can set all parameter for all stages. To test them click `Reconstruct`. If the parameters work well, you can save them to the current beamtime folder using the `Save as` at the lower left. \nIf you want to reconstruct the whole scan you can click `Submit All` after chosing the Options. If you select `Custom` it will take the parameters from the left. \n\n### Other changes during beamtime\n\nIf you change the detector or anything else like removing tasks adapt parameters the full config files are located in the `beamtime/processed/holowizard_config/`folder. Changes here will reflect onto future curl requests!\n\n## The Forge\n\nThis framework can be used to generate large datasets of simulated holograms of randomly sampled objects. \n\n### Create New Dataset\n\nOpen a terminal and create a new config file with \n\n```{bash}\n$ holowziard_forge_create_testconfig <args>\n```\n\n| Argument | Description | Position |\n|-----------------|-----------------------------------------------------------|----------|\n| `name` | Name of the new config file (without file name extension) | 1 |\n| `--output_dir` | Output directory | optional |\n| `--override` | Overrides existing configuration file | optional |\n\n\nThe config file can then be customized and used to create a new dataset with\n\n```{bash}\n$ holowizard_forge_generate_data <args>\n```\n\n| Argument | Description | Position |\n|---------------|------------------------------------------------------|----------|\n| `config` | Path to the custom configuration file. | 1 |\n| `output_dir` | Output directory where the generated data is stored. | 2 |\n| `num_samples` | Number of data samples that should be generated. | 3 |\n| `--override` | Override the output folder if it already exists. | optional |\n\n### Output Structure\n```\noutput/\n\u2514\u2500\u2500 train.hdf5\n\u2514\u2500\u2500 train.json\n```\n\nThe file train.hdf5 contains the training data\nThe file `train.json` contains the config parameters which have been used for the training data creation.\n\n### Developer Info\n\n#### Add new Parameters\nTo add a new parameter, add it to the default configuration `holowizard/forge/configs/default.json`.\n\n## The Livereco\n\nStart the online reconstruction server with\n\n```{bash}\n$ holowizard_livereco_server_start\n```\n\n# Citations\n### Artifact-suppressing reconstruction method:\n- URL: https://opg.optica.org/oe/fulltext.cfm?uri=oe-32-7-10801&id=547807###\n- DOI: 10.1364/OE.514641\n\n```{bibtex}\n@article{Dora:24,\nauthor = {Johannes Dora and Martin M\\\"{o}ddel and Silja Flenner and Christian G. Schroer and Tobias Knopp and Johannes Hagemann},\njournal = {Opt. Express},\nkeywords = {Free electron lasers; Holographic microscopy; Imaging techniques; Phase shift; X-ray imaging; Zone plates},\nnumber = {7},\npages = {10801--10828},\npublisher = {Optica Publishing Group},\ntitle = {{Artifact-suppressing reconstruction of strongly interacting objects in X-ray near-field holography without a spatial support constraint}},\nvolume = {32},\nmonth = {Mar},\nyear = {2024},\nurl = {https://opg.optica.org/oe/abstract.cfm?URI=oe-32-7-10801},\ndoi = {10.1364/OE.514641},\nabstract = {The phase problem is a well known ill-posed reconstruction problem of coherent lens-less microscopic imaging, where only the squared magnitude of a complex wavefront is measured by a detector while the phase information of the wave field is lost. To retrieve the lost information, common algorithms rely either on multiple data acquisitions under varying measurement conditions or on the application of strong constraints such as a spatial support. In X-ray near-field holography, however, these methods are rendered impractical in the setting of time sensitive in situ and operando measurements. In this paper, we will forego the spatial support constraint and propose a projected gradient descent (PGD) based reconstruction scheme in combination with proper preprocessing and regularization that significantly reduces artifacts for refractive reconstructions from only a single acquired hologram without a spatial support constraint. We demonstrate the feasibility and robustness of our approach on different data sets obtained at the nano imaging endstation of P05 at PETRA III (DESY, Hamburg) operated by Helmholtz-Zentrum Hereon.},\n}\n```\n\n### Model-based autofocus:\n- URL: https://opg.optica.org/oe/abstract.cfm?doi=10.1364/OE.544573\n- DOI: 10.1364/OE.544573\n\n```{bibtex}\n@article{Dora:25,\nauthor = {Johannes Dora and Martin M\\\"{o}ddel and Silja Flenner and Jan Reimers and Berit Zeller-Plumhoff and Christian G. Schroer and Tobias Knopp and Johannes Hagemann},\njournal = {Opt. Express},\nkeywords = {Image analysis; Image metrics; Imaging systems; Phase retrieval; X-ray imaging; Zone plates},\nnumber = {4},\npages = {6641--6657},\npublisher = {Optica Publishing Group},\ntitle = {Model-based autofocus for near-field phase retrieval},\nvolume = {33},\nmonth = {Feb},\nyear = {2025},\nurl = {https://opg.optica.org/oe/abstract.cfm?URI=oe-33-4-6641},\ndoi = {10.1364/OE.544573},\n}\n```\n\n## Further links\nhttps://helmholtz.software/software/holowizard \\\nhttps://connect.helmholtz-imaging.de/solution/71 \\\nhttps://connect.helmholtz-imaging.de/blog_gallery/blogpost/10 \n",
"bugtrack_url": null,
"license": null,
"summary": null,
"version": "2.0.1",
"project_urls": {
"Paper_ASRM": "https://doi.org/10.1364/OE.514641",
"Paper_Autofocus": "https://doi.org/10.1364/OE.544573",
"Repository": "https://github.com/DESY-FS-PETRA/holowizard",
"Zenodo": "https://doi.org/10.5281/zenodo.8349364"
},
"split_keywords": [
"near-field holography",
" phase retrieval",
" tomography"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "31e9d3aa80866ae083f06256d74e27c1989816539437a0c1127fb836e8c57081",
"md5": "883386a5f9b7a428d7486db81857cfd7",
"sha256": "4d13c79198cb4a00e1290ba969d58c67cc07144a89ee7ed810b341505141aa7f"
},
"downloads": -1,
"filename": "holowizard-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "883386a5f9b7a428d7486db81857cfd7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.11",
"size": 583252,
"upload_time": "2025-07-22T12:38:00",
"upload_time_iso_8601": "2025-07-22T12:38:00.748969Z",
"url": "https://files.pythonhosted.org/packages/31/e9/d3aa80866ae083f06256d74e27c1989816539437a0c1127fb836e8c57081/holowizard-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c686df0d0bdd533ad80d8d79ded67242123e5973fb6d10f05ffde33b80165a5b",
"md5": "0b9e0f00aef23b37d19a64cb3a20b6a6",
"sha256": "678d11846737d068c20e02b60b2f1cf71f812c7329c8b9bdf9d0909ed4c60517"
},
"downloads": -1,
"filename": "holowizard-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "0b9e0f00aef23b37d19a64cb3a20b6a6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.11",
"size": 485307,
"upload_time": "2025-07-22T12:38:02",
"upload_time_iso_8601": "2025-07-22T12:38:02.278990Z",
"url": "https://files.pythonhosted.org/packages/c6/86/df0d0bdd533ad80d8d79ded67242123e5973fb6d10f05ffde33b80165a5b/holowizard-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-22 12:38:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DESY-FS-PETRA",
"github_project": "holowizard",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "tqdm",
"specs": []
},
{
"name": "numpy",
"specs": [
[
"==",
"1.26.4"
]
]
},
{
"name": "torch",
"specs": []
},
{
"name": "torchvision",
"specs": []
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "h5py",
"specs": []
},
{
"name": "hdf5plugin",
"specs": []
},
{
"name": "selenium",
"specs": []
},
{
"name": "bs4",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "xraylib",
"specs": []
},
{
"name": "cupy-cuda12x",
"specs": []
},
{
"name": "pyzmq",
"specs": []
},
{
"name": "pyqt5-tools",
"specs": []
},
{
"name": "scikit-learn",
"specs": []
},
{
"name": "scikit-image",
"specs": []
},
{
"name": "GitPython",
"specs": []
},
{
"name": "dask",
"specs": []
},
{
"name": "dask_jobqueue",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "bokeh",
"specs": []
},
{
"name": "scipy",
"specs": []
},
{
"name": "astra-toolbox",
"specs": []
},
{
"name": "pyqtgraph",
"specs": []
},
{
"name": "uvicorn",
"specs": []
},
{
"name": "hydra-core",
"specs": []
},
{
"name": "fastapi",
"specs": []
},
{
"name": "markdown",
"specs": []
},
{
"name": "plotly",
"specs": []
}
],
"lcname": "holowizard"
}
JSON
