Skip to content

Commit 88b5a8d

Browse files
paquiteauchaithyagr
paquiteau
and
chaithyagr
committed
Readme upgrade (#321)
* feat: update MRI-NUFFT figure * feat: update README * refactor: reorganize README * Update README.rst Co-authored-by: Chaithya G R <[email protected]> --------- Co-authored-by: Chaithya G R <[email protected]>
1 parent ca85c64 commit 88b5a8d

File tree

4 files changed

+46991
-8621
lines changed

4 files changed

+46991
-8621
lines changed

‎README.rst‎

Lines changed: 117 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,76 @@
1-
=========
2-
MRI-NUFFT
3-
=========
1+
|centerdiv|
42

5-
Doing non-Cartesian MR Imaging has never been so easy.
3+
.. image:: https://github.com/mind-inria/mri-nufft/raw/master/docs/_static/logos/mri-nufft.png
4+
:width: 300
5+
:align: center
6+
7+
|
68
7-
.. list-table::
8-
:widths: 25 25 25
9-
:header-rows: 0
9+
|Docs| |PyPI| |JOSS|
10+
|Coverage| |CI| |CD| |Style|
1011

11-
* - .. image:: https://mind-inria.github.io/mri-nufft/_static/coverage_badge.svg
12-
- .. image:: https://github.com/mind-inria/mri-nufft/actions/workflows/test-ci.yml/badge.svg
13-
- .. image:: https://github.com/mind-inria/mri-nufft/workflows/CD/badge.svg
14-
* - .. image:: https://img.shields.io/badge/style-black-black
15-
- .. image:: https://img.shields.io/badge/docs-Sphinx-blue
16-
:target: https://mind-inria.github.io/mri-nufft
17-
- .. image:: https://img.shields.io/pypi/v/mri-nufft
18-
:target: https://pypi.org/project/mri-nufft/
1912

13+
*Doing non-Cartesian MR Imaging has never been so easy*
2014

21-
This python package extends various NUFFT (Non-Uniform Fast Fourier Transform) python bindings used for MRI reconstruction.
15+
|enddiv|
2216

23-
In particular, it provides a unified interface for all the methods, with extra features such as coil sensitivity, density compensated adjoint and off-resonance corrections (for static B0 inhomogeneities).
2417

25-
.. raw:: html
18+
Introduction
19+
------------
2620

27-
<div align="center">
2821

29-
.. image:: https://github.com/mind-inria/mri-nufft/raw/master/docs/_static/mri-nufft-scheme.svg
22+
MRI-NUFFT is an open-source Python library that provides state-of-the-art non-Cartesian MRI tools: trajectories, data loading and fast and memory-efficient operators to be used on laptops, clusters, and MRI consoles.
23+
24+
In particular, it provides a unified interface for computing Non-Uniform Fast Fourier Transform (`NUFFT <https://mind-inria.github.io/mri-nufft/nufft.html>`_), using the specialized backend of your choice (|finufft|_, |gpunufft|_, |torchkbnufft|_, ... ), and with integrated MRI-specific features such as:
25+
26+
- `multi-coil support <https://mind-inria.github.io/mri-nufft/generated/_autosummary/mrinufft.extras.smaps.html>`__ ,
27+
- `density compensation <https://mind-inria.github.io/mri-nufft/generated/_autosummary/mrinufft.density.html>`__,
28+
- `off-resonance correction <https://mind-inria.github.io/mri-nufft/generated/autoexamples/operators/example_offresonance.html>`__.
29+
- `autodiff support <https://mind-inria.github.io/mri-nufft/generated/autoexamples/GPU/index.html>`__.
30+
31+
32+
MRI-nufft is a nice and polite piece of software, that will return the same type of array (e.g ``numpy``, ``cupy``, ``torch``) provided at input, without extra copies for conversions.
33+
34+
35+
On top of that we ship a variety of `non-Cartesian trajectories <https://mind-inria.github.io/mri-nufft/generated/autoexamples/trajectories/index.html>`__ commonly used by the MRI community, and even `tools <https://mind-inria.github.io/mri-nufft/generated/autoexamples/trajectories/example_trajectory_tools.html>`__ to helps you develop new ones.
36+
37+
|centerdiv|
38+
39+
.. image:: https://github.com/mind-inria/mri-nufft/raw/master/docs/_static/mri-nufft-scheme.png
3040
:width: 700
3141
:align: center
3242

33-
Modularity and Integration of MRI-nufft with the python computing libraries.
43+
*Modularity and Integration of MRI-nufft with the python computing libraries.*
44+
45+
|enddiv|
3446

35-
.. raw:: html
36-
37-
</div>
3847

3948
Usage
40-
=====
49+
-----
4150

4251
.. TODO use a include file directive.
4352
.. code-block:: python
4453
45-
from scipy.datasets import face # For demo
46-
import numpy as np
47-
import mrinufft
48-
from mrinufft.trajectories import display
49-
from mrinufft.density import voronoi
50-
51-
# Create 2D Radial trajectories for demo
52-
samples_loc = mrinufft.initialize_2D_radial(Nc=100, Ns=500)
53-
# Get a 2D image for the demo (512x512)
54-
image = np.complex64(face(gray=True)[256:768, 256:768])
55-
56-
## The real deal starts here ##
57-
# Choose your NUFFT backend (installed independently from the package)
58-
# pip install mri-nufft[finufft] will be just fine here
59-
NufftOperator = mrinufft.get_operator("finufft")
54+
from scipy.datasets import face # For demo
55+
import numpy as np
56+
import mrinufft
6057
61-
# For improved image reconstruction, use density compensation
62-
density = voronoi(samples_loc.reshape(-1, 2))
58+
# Create 2D Radial trajectories for demo
59+
samples_loc = mrinufft.initialize_2D_radial(Nc=100, Ns=500)
60+
# Get a 2D image for the demo (512x512)
61+
image = np.complex64(face(gray=True)[256:768, 256:768])
6362
64-
# And create the associated operator.
65-
nufft = NufftOperator(
66-
samples_loc.reshape(-1, 2), shape=image.shape, density=density, n_coils=1
67-
)
63+
## The real deal starts here ##
64+
# Choose your NUFFT backend (installed independently from the package)
65+
# pip install mri-nufft[finufft] will be just fine here
66+
nufft = mrinufft.get_operator("finufft",
67+
samples_loc, shape=image.shape, density="voronoi", n_coils=1
68+
)
6869
69-
kspace_data = nufft.op(image) # Image -> Kspace
70-
image2 = nufft.adj_op(kspace_data) # Kspace -> Image
70+
kspace_data = nufft.op(image) # Image -> Kspace
71+
image2 = nufft.adj_op(kspace_data) # Kspace -> Image
7172
72-
73-
.. TODO Add image
73+
pinv = nufft.pinv_solver(kspace_data) # get a Pseudo inverse (least square minimization)
7474
7575
For improved image quality, embed these steps in a more complex reconstruction pipeline (for instance using `PySAP <https://github.com/CEA-COSMIC/pysap-mri>`_).
7676

@@ -84,7 +84,7 @@ Want to see more ?
8484
Installation
8585
------------
8686

87-
MRI-nufft is available on Pypi and can be installed with::
87+
MRI-nufft is available on `PyPi <https://pypi.org/project/mri-nufft>`__ and can be installed with::
8888

8989
pip install mri-nufft
9090

@@ -110,5 +110,70 @@ Here are several project that rely on MRI-NUFFT:
110110
- `snake-fmri <https://github.com/paquiteau/snake-fmri>`_
111111
- `deepinv <https://github.com/deepinv/deepinv>`_
112112

113+
Add yours by opening a PR or an issue, let us know how you use MRI-nufft !
114+
115+
116+
How to cite MRI-NUFFT
117+
---------------------
118+
119+
We published MRI-NUFFT at `JOSS <https://doi.org/10.21105/joss.07743>`__ ::
120+
121+
Comby et al., (2025). MRI-NUFFT: Doing non-Cartesian MRI has never been easier. Journal of Open Source Software, 10(108), 7743, https://doi.org/10.21105/joss.07743
122+
123+
.. code:: bibtex
124+
125+
@article{Comby2025, doi = {10.21105/joss.07743},
126+
author = {Comby, Pierre-Antoine and Daval-Frérot, Guillaume and Pan, Caini and Tanabene, Asma and Oudjman, Léna and Cencini, Matteo and Ciuciu, Philippe and GR, Chaithya},
127+
title = {MRI-NUFFT: Doing non-Cartesian MRI has never been easier}, journal = {Journal of Open Source Software},
128+
url = {https://doi.org/10.21105/joss.07743},
129+
year = {2025},
130+
publisher = {The Open Journal},
131+
volume = {10},
132+
number = {108},
133+
pages = {7743},
134+
}
135+
136+
137+
Contributing
138+
------------
139+
140+
We warmly welcome contributions ! Check out our `guidelines <https://github.com/mind-inria/mri-nufft/blob/master/CONTRIBUTING.md>`_ ,
141+
Don't hesitate to look for unsolved `issues <https://github.com/mind-inria/mri-nufft/issues/>`__
142+
143+
144+
145+
.. raw:: html
146+
147+
<div align="center"><em> ✨ If you made it this far, consider starring the repo ✨ <em></div>
148+
149+
150+
151+
.. |Coverage| image:: https://mind-inria.github.io/mri-nufft/_static/coverage_badge.svg
152+
.. |CI| image:: https://github.com/mind-inria/mri-nufft/actions/workflows/test-ci.yml/badge.svg
153+
.. |CD| image:: https://github.com/mind-inria/mri-nufft/workflows/CD/badge.svg
154+
.. |Style| image:: https://img.shields.io/badge/style-black-black
155+
.. |Docs| image:: https://img.shields.io/badge/docs-Sphinx-blue
156+
:target: https://mind-inria.github.io/mri-nufft
157+
.. |PyPI| image:: https://img.shields.io/pypi/v/mri-nufft
158+
:target: https://pypi.org/project/mri-nufft/
159+
.. |JOSS| image:: https://joss.theoj.org/papers/10.21105/joss.07743/status.svg
160+
:target: https://doi.org/10.21105/joss.07743
161+
162+
.. |finufft| replace:: ``(cu)finufft``
163+
.. _finufft: https://github.com/flatironinstitute/finufft
164+
165+
.. |gpunufft| replace:: ``gpunufft``
166+
.. _gpunufft: https://github.com/chaihtyagr/gpunufft
167+
168+
.. |torchkbnufft| replace:: ``torchkbnufft``
169+
.. _torchkbnufft: https://github.com/mmuckley/torchkbnufft
170+
171+
172+
173+
.. |centerdiv| raw:: html
174+
175+
<div align="center">
176+
177+
.. |enddiv| raw:: html
113178

114-
Add yours by opening a PR !
179+
</div>

‎docs/_static/mri-nufft-scheme.png‎

274 KB
Loading

0 commit comments

Comments
 (0)