# cdiutils
[](https://zenodo.org/badge/latestdoi/360442527)
[](https://github.com/clatlan/cdiutils/blob/main/LICENSE)
My python package to help X-ray Bragg Coherent Diffraction Imaging (BCDI) practitioners in their analysis and visualisation workflows. I developed the package during my PhD.
The package is designed to handle the three primary stages of a BCDI data processing workflow:
* **Pre-processing** (data centering and cropping)
* **Phase retrieval**: utilises PyNX for accurate phasing (refer to [PyNX documentation](https://pynx.esrf.fr/en/latest/)).
* **Post-processing** (orthogonalisation, phase manipulation, strain computation etc.)
It is assumed that the phase retrieval is conducted using the PyNX package. The `BcdiPipeline` class runs all three stages and can manage connections to different machines, especially for GPU-based phase retrieval.
Some features of this package include:
* **Flexibility in Hardware:** While the phase retrieval stage may leverage GPUs, pre- and post-processing can be executed without GPU support.
* **Utility Functions:** The package provides utility functions to analyse processed data and generate plots suitable for potential publications.
For a visual wrap-up, see the associated poster presented at [XTOP24](https://xtop2024.sciencesconf.org/):
## Installation
### Using conda (recommended)
Create a new conda environment with all dependencies:
```bash
# Clone the repository first
git clone https://github.com/clatlan/cdiutils.git
cd cdiutils
# Create conda environment from environment.yml
conda env create -f environment.yml
# Activate the environment
conda activate cdiutils
# Install cdiutils in development mode
pip install -e .
```
For development (includes documentation and testing tools):
```bash
# Create development environment
conda env create -f environment-dev.yml
conda activate cdiutils-dev
pip install -e .
```
### Using pip (from PyPI - coming soon)
Once published on PyPI, you'll be able to install directly:
```bash
pip install cdiutils
```
### Using pip (from GitHub - current method)
You can install the package directly from GitHub:
```bash
pip install git+https://github.com/clatlan/cdiutils.git
```
To update your environment with the latest commits:
```bash
pip install -I --no-deps git+https://github.com/clatlan/cdiutils.git
```
_Note: Check out the dev branch for the latest features and bug fixes. The dev branch is not guaranteed to be stable._
Upgrade your environment with a new version of the package:
```bash
pip install -U git+https://github.com/clatlan/cdiutils.git
```
## Getting started
Once the package is installed, you can try it right away using the notebook template directly accessible with the command:
```bash
prepare_bcdi_notebook [path_to_destination]
```
This will generate a notebook template at the given destination.
## Processing BCDI data
Once data are processed, the `BcdiPipeline` instance saves the data in .npz, .cxi and .vti files following the CXI file format convention (see [https://www.cxidb.org/cxi.html]()). It also plots summary and debug figures such as:
* **Summary Slice Plot**
* **Isosurface determination**
* **Different strain computation methods**
## BCDI reconstruction analysis
If want to analyse and compare your reconstructions, check out the example notebook [bcdi_reconstruction_analysis.ipynb](https://github.com/clatlan/cdiutils/blob/master/examples/bcdi_reconstruction_analysis.ipynb) in the `examples` folder. This notebook provides a comprehensive overview of the analysis process, including:
* **Slice plots of any quantity you like (here phase) across different conditions:**
* **Reciprocal space plots in the orthogonal frame (lab frame)**
* **Histogram plots of any quantity you like across different conditions:**
## Cross section quiver
The cross section quiver is nice tool for visualising the strain and displacement fields and their relationship in BCDI data.
* The cross section quiver allows to plot cross section of strain and displacement field on the same plot.
* For different conditions
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Support
If you encounter any issues or have questions, please open an issue on the [GitHub repository](https://github.com/clatlan/cdiutils/issues).
Raw data
{
"_id": null,
"home_page": null,
"name": "cdiutils",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Clement Atlan <clement.atlan@esrf.fr>",
"keywords": "reconstruction, coherent X-ray imaging, Bragg, pipeline, synchrotron radiation, quantitative analysis",
"author": "Corentin Chatelier, David Simonne, Matthieu Deschamps, Kyle Olson",
"author_email": "Clement Atlan <clement.atlan@esrf.fr>",
"download_url": "https://files.pythonhosted.org/packages/b6/9b/b53eefab3534888a010ec650c3dfb77d479d2b99852c83586bc999df81a4/cdiutils-0.2.0.tar.gz",
"platform": null,
"description": "# cdiutils\n\n[](https://zenodo.org/badge/latestdoi/360442527)\n\n[](https://github.com/clatlan/cdiutils/blob/main/LICENSE)\n\nMy python package to help X-ray Bragg Coherent Diffraction Imaging (BCDI) practitioners in their analysis and visualisation workflows. I developed the package during my PhD.\n\nThe package is designed to handle the three primary stages of a BCDI data processing workflow:\n\n* **Pre-processing** (data centering and cropping)\n* **Phase retrieval**: utilises PyNX for accurate phasing (refer to [PyNX documentation](https://pynx.esrf.fr/en/latest/)).\n* **Post-processing** (orthogonalisation, phase manipulation, strain computation etc.)\n\nIt is assumed that the phase retrieval is conducted using the PyNX package. The `BcdiPipeline` class runs all three stages and can manage connections to different machines, especially for GPU-based phase retrieval.\n\nSome features of this package include:\n\n* **Flexibility in Hardware:** While the phase retrieval stage may leverage GPUs, pre- and post-processing can be executed without GPU support.\n* **Utility Functions:** The package provides utility functions to analyse processed data and generate plots suitable for potential publications.\n\nFor a visual wrap-up, see the associated poster presented at [XTOP24](https://xtop2024.sciencesconf.org/):\n\n\n\n## Installation\n\n### Using conda (recommended)\n\nCreate a new conda environment with all dependencies:\n\n```bash\n# Clone the repository first\ngit clone https://github.com/clatlan/cdiutils.git\ncd cdiutils\n\n# Create conda environment from environment.yml\nconda env create -f environment.yml\n\n# Activate the environment\nconda activate cdiutils\n\n# Install cdiutils in development mode\npip install -e .\n```\n\nFor development (includes documentation and testing tools):\n\n```bash\n# Create development environment\nconda env create -f environment-dev.yml\nconda activate cdiutils-dev\npip install -e .\n```\n\n### Using pip (from PyPI - coming soon)\n\nOnce published on PyPI, you'll be able to install directly:\n\n```bash\npip install cdiutils\n```\n\n### Using pip (from GitHub - current method)\n\nYou can install the package directly from GitHub:\n\n```bash\npip install git+https://github.com/clatlan/cdiutils.git\n```\n\nTo update your environment with the latest commits:\n\n```bash\npip install -I --no-deps git+https://github.com/clatlan/cdiutils.git\n```\n\n_Note: Check out the dev branch for the latest features and bug fixes. The dev branch is not guaranteed to be stable._\n\nUpgrade your environment with a new version of the package:\n\n```bash\npip install -U git+https://github.com/clatlan/cdiutils.git\n```\n\n## Getting started\n\nOnce the package is installed, you can try it right away using the notebook template directly accessible with the command:\n\n```bash\nprepare_bcdi_notebook [path_to_destination]\n```\n\nThis will generate a notebook template at the given destination.\n\n## Processing BCDI data\n\nOnce data are processed, the `BcdiPipeline` instance saves the data in .npz, .cxi and .vti files following the CXI file format convention (see [https://www.cxidb.org/cxi.html]()). It also plots summary and debug figures such as:\n\n* **Summary Slice Plot**\n \n* **Isosurface determination**\n \n* **Different strain computation methods**\n \n\n## BCDI reconstruction analysis\nIf want to analyse and compare your reconstructions, check out the example notebook [bcdi_reconstruction_analysis.ipynb](https://github.com/clatlan/cdiutils/blob/master/examples/bcdi_reconstruction_analysis.ipynb) in the `examples` folder. This notebook provides a comprehensive overview of the analysis process, including:\n* **Slice plots of any quantity you like (here phase) across different conditions:**\n \n\n\n* **Reciprocal space plots in the orthogonal frame (lab frame)**\n \n\n* **Histogram plots of any quantity you like across different conditions:**\n \n\n\n## Cross section quiver\nThe cross section quiver is nice tool for visualising the strain and displacement fields and their relationship in BCDI data. \n\n* The cross section quiver allows to plot cross section of strain and displacement field on the same plot.\n \n* For different conditions\n \n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Support\n\nIf you encounter any issues or have questions, please open an issue on the [GitHub repository](https://github.com/clatlan/cdiutils/issues).\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python package for (Bragg) Coherent X-ray Diffraction Imaging processing, analysis and visualisation workflows.",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/clatlan/cdiutils"
},
"split_keywords": [
"reconstruction",
" coherent x-ray imaging",
" bragg",
" pipeline",
" synchrotron radiation",
" quantitative analysis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f7998dcd98707583f85d3e746dadc82833a261c492cfa609fa261a44075695b2",
"md5": "31129edaf2cd65278343ebe923c55f1c",
"sha256": "6e4b8228ebfe0119df28f53d65af614060bb9615e728dbaa95fa50fbdc95fa56"
},
"downloads": -1,
"filename": "cdiutils-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "31129edaf2cd65278343ebe923c55f1c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 206316,
"upload_time": "2025-08-05T08:45:58",
"upload_time_iso_8601": "2025-08-05T08:45:58.541483Z",
"url": "https://files.pythonhosted.org/packages/f7/99/8dcd98707583f85d3e746dadc82833a261c492cfa609fa261a44075695b2/cdiutils-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b69bb53eefab3534888a010ec650c3dfb77d479d2b99852c83586bc999df81a4",
"md5": "3742c8de29cd006a43dd772facf28309",
"sha256": "9b3200a7918e017f439665c17b255bac183734036e804a7a7ee57ddfe8c9297b"
},
"downloads": -1,
"filename": "cdiutils-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "3742c8de29cd006a43dd772facf28309",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 2520089,
"upload_time": "2025-08-05T08:46:00",
"upload_time_iso_8601": "2025-08-05T08:46:00.672960Z",
"url": "https://files.pythonhosted.org/packages/b6/9b/b53eefab3534888a010ec650c3dfb77d479d2b99852c83586bc999df81a4/cdiutils-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-05 08:46:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "clatlan",
"github_project": "cdiutils",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "colorcet",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "h5py",
"specs": [
[
">=",
"3.6.0"
]
]
},
{
"name": "hdf5plugin",
"specs": [
[
">=",
"3.2.0"
]
]
},
{
"name": "ipykernel",
"specs": []
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.8"
]
]
},
{
"name": "numpy",
"specs": []
},
{
"name": "pandas",
"specs": [
[
">=",
"1.4.2"
]
]
},
{
"name": "scikit-image",
"specs": [
[
">=",
"0.19.2"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
">=",
"1.1.3"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.8.0"
]
]
},
{
"name": "seaborn",
"specs": [
[
">=",
"0.12.1"
]
]
},
{
"name": "silx",
"specs": []
},
{
"name": "tabulate",
"specs": []
},
{
"name": "xrayutilities",
"specs": [
[
">=",
"1.7.3"
]
]
},
{
"name": "ipyvolume",
"specs": []
},
{
"name": "ipython_genutils",
"specs": []
},
{
"name": "bokeh",
"specs": []
},
{
"name": "panel",
"specs": []
},
{
"name": "tornado",
"specs": []
},
{
"name": "sphinx",
"specs": [
[
">=",
"4.0"
]
]
},
{
"name": "pydata-sphinx-theme",
"specs": []
}
],
"lcname": "cdiutils"
}
JSON
