# NIfTI to GIF
## Foreword
The following repository is heavily based on [Gif_your_nifti](https://github.com/lukassnoek/nifti2gif) package by [Lukas Snoek](https://github.com/lukassnoek). I forked the repository, and I pushed it to the PyPI repository, so that it is now available via the `pip` command. See the PyPI repository of the `nifti2gif` project: https://pypi.org/project/nifti2gif/
## Quick installation
In order to install:
```shell
pip install nifti2gif
```
Basic usage in a notebook or a script:
```python
import nifti2gif.core as nifti2gif
nifti2gif.write_gif_normal('./some_nifti_file.nii')
```
See example usage: https://www.kaggle.com/code/mikolajbuchwald/3d-mri-brain-tumor-segmentation-u-net
Create a nice looking gifs from your nifti (`.nii` or `.nii.gz`) files with a simple command:
```
gif_your_nifti /path/to/data.nii
```
<img src="gifs/Me_2014_grayscale.gif">
# Getting started
## Dependencies
| Package | Tested version |
|-------------------------------------------|----------------|
| [NumPy](http://www.numpy.org/) | 1.14.2 |
| [NiBabel](http://nipy.org/nibabel/) | 2.2.1 |
| [matplotlib](http://matplotlib.org/) | 2.2.0 |
| [imageio](https://imageio.github.io/) | 2.2.0 |
| [scikit-image](https://scikit-image.org/) | 0.13.0 |
## Installation
Navigate to the main page of the repository and clone it. Then, change directory to the cloned repository and run:
```
pip install -r requirements.txt
python setup.py install
```
## Docker
Build a docker container with:
```
docker build -t gif_your_nifti .
```
Run with docker:
```
docker run --rm -v /path/to/nifti/:/data gif_your_nifti:latest /data/image.nii
```
## Examples
For the examples below, I've downloaded [ICBM 2009c Nonlinear Asymmetric](http://www.bic.mni.mcgill.ca/~vfonov/icbm/2009/mni_icbm152_nlin_asym_09c_nifti.zip) and used the T1 and gray matter template thereof.
It is also possible to use your own brain image, as I will show below. The only thing that you need to make sure is, that your brain image has the right orientation. You can reorient your NIfTI image according to the MNI template standard with the FSL command: `fslreorient2std my_brain.nii my_brain.nii`.
### Grayscale GIF
To create a simple gray scale gif, type the following command in your commandline:
```
gif_your_nifti /path/to/mni_icbm152_t1_tal_nlin_asym_09c.nii
```
<img src="gifs/mni_icbm152_t1_tal_nlin_asym_09c.gif">
### Pseudocolor GIF
To create a [pseudocolor](https://en.wikipedia.org/wiki/False_color#Pseudocolor) gif, type the following command in your commandline:
```
gif_your_nifti /path/to/Me_2014.nii --mode pseudocolor --cmap plasma
```
<img src="gifs/mni_icbm152_t1_tal_nlin_asym_09c_plasma.gif">
The colormap can be any colormap from the [matplotlib colormaps](https://matplotlib.org/examples/color/colormaps_reference.html).
### Depth GIF
To create a depth gif, type the following command in your commandline:
```
gif_your_nifti /path/to/mni_icbm152_t1_tal_nlin_asym_09c.nii --mode depth
```
<img src="gifs/mni_icbm152_gm_tal_nlin_asym_09c_depth.gif">
The image shows you in color what the value of the next slice will be. If the color is slightly red or blue it means that the value on the next slide is brighter or darker, respectifely. It therefore encodes a certain kind of depth into the gif.
### RGB GIF
To create a Red Blue Green (RGB) gif, type the following command in your commandline:
```
gif_your_nifti /path/to/gm.nii /path/to/wm.nii /path/to/csf.nii --mode rgb
```
<img src="gifs/mni_icbm152_gm_tal_nlin_asym_09c_rgb.gif">
This image takes the values from the first NIfTI file as its red colors, second NIfTI file as its green colors and third NIfTI as its blue colors.
## Resize GIF
It is also possible to change the size of a gif, by changing the `size` parameter in any function above. The following are examples of resizing the images to 50% of it's original size, with:
```
gif_your_nifti /path/to/mni_icbm152_gm_tal_nlin_asym_09c.nii --size 0.5
gif_your_nifti /path/to/mni_icbm152_gm_tal_nlin_asym_09c.nii --size 0.5 --mode pseudocolor --cmap cubehelix
gif_your_nifti /path/to/mni_icbm152_gm_tal_nlin_asym_09c.nii --size 0.5 --mode pseudocolor --cmap inferno
gif_your_nifti /path/to/mni_icbm152_gm_tal_nlin_asym_09c.nii --size 0.5 --mode pseudocolor --cmap viridis
```
<img src="gifs/mni_icbm152_gm_tal_nlin_asym_09c.gif">
<img src="gifs/mni_icbm152_gm_tal_nlin_asym_09c_cubehelix.gif">
<img src="gifs/mni_icbm152_gm_tal_nlin_asym_09c_inferno.gif">
<img src="gifs/mni_icbm152_gm_tal_nlin_asym_09c_viridis.gif">
Changing the size of a gif also changes the frames per second parameter, so that the overall tempo stays the same. Meaning, if you have a gif of original size with 20 frames per second (fps), changing the size to 50%, will cause the smaller gif to run at 10 fps, so that both take the same amount for a cycle.
### Use within a python script
You can also use `gif_your_nifti` from a python script. See [script examples](examples/example_script.py) for further information.
## Uploading to PyPI repository
Build the project:
```shell
python setup.py sdist
```
Upload with `twine` (`pip install twine`):
```shell
twine upload dist/*
```
Type your username and password to PyPI.
### Troubleshooting with uploading to PyPI
Check, e.g., for syntax errors in the description file (README):
```shell
twine check dist/*
```
# License
This project is licensed under [BSD 3-Clause License](LICENSE.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/mikbuch/nifti2gif",
"name": "nifti2gif",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "nifti,gif",
"author": "Mikolaj Buchwald",
"author_email": "mikolaj.buchwald@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/40/d8/83c6affbf19d9f81b3818f93cce561b4ce705325d374c3f7f63cb8b93442/nifti2gif-0.0.5.tar.gz",
"platform": null,
"description": "# NIfTI to GIF\n\n## Foreword\n\nThe following repository is heavily based on [Gif_your_nifti](https://github.com/lukassnoek/nifti2gif) package by [Lukas Snoek](https://github.com/lukassnoek). I forked the repository, and I pushed it to the PyPI repository, so that it is now available via the `pip` command. See the PyPI repository of the `nifti2gif` project: https://pypi.org/project/nifti2gif/\n\n## Quick installation\n\nIn order to install:\n\n```shell\npip install nifti2gif\n```\n\nBasic usage in a notebook or a script:\n\n```python\nimport nifti2gif.core as nifti2gif\n\nnifti2gif.write_gif_normal('./some_nifti_file.nii')\n```\n\nSee example usage: https://www.kaggle.com/code/mikolajbuchwald/3d-mri-brain-tumor-segmentation-u-net\n\nCreate a nice looking gifs from your nifti (`.nii` or `.nii.gz`) files with a simple command:\n\n```\ngif_your_nifti /path/to/data.nii\n```\n<img src=\"gifs/Me_2014_grayscale.gif\">\n\n# Getting started\n\n## Dependencies\n\n| Package | Tested version |\n|-------------------------------------------|----------------|\n| [NumPy](http://www.numpy.org/) | 1.14.2 |\n| [NiBabel](http://nipy.org/nibabel/) | 2.2.1 |\n| [matplotlib](http://matplotlib.org/) | 2.2.0 |\n| [imageio](https://imageio.github.io/) | 2.2.0 |\n| [scikit-image](https://scikit-image.org/) | 0.13.0 |\n\n## Installation\n\nNavigate to the main page of the repository and clone it. Then, change directory to the cloned repository and run:\n```\npip install -r requirements.txt\npython setup.py install\n```\n\n## Docker\n\nBuild a docker container with:\n\n```\ndocker build -t gif_your_nifti .\n```\n\nRun with docker:\n\n```\ndocker run --rm -v /path/to/nifti/:/data gif_your_nifti:latest /data/image.nii\n```\n\n## Examples\n\nFor the examples below, I've downloaded [ICBM 2009c Nonlinear Asymmetric](http://www.bic.mni.mcgill.ca/~vfonov/icbm/2009/mni_icbm152_nlin_asym_09c_nifti.zip) and used the T1 and gray matter template thereof.\n\nIt is also possible to use your own brain image, as I will show below. The only thing that you need to make sure is, that your brain image has the right orientation. You can reorient your NIfTI image according to the MNI template standard with the FSL command: `fslreorient2std my_brain.nii my_brain.nii`.\n\n### Grayscale GIF\n\nTo create a simple gray scale gif, type the following command in your commandline:\n\n```\ngif_your_nifti /path/to/mni_icbm152_t1_tal_nlin_asym_09c.nii\n```\n<img src=\"gifs/mni_icbm152_t1_tal_nlin_asym_09c.gif\">\n\n\n### Pseudocolor GIF\n\nTo create a [pseudocolor](https://en.wikipedia.org/wiki/False_color#Pseudocolor) gif, type the following command in your commandline:\n```\ngif_your_nifti /path/to/Me_2014.nii --mode pseudocolor --cmap plasma\n```\n<img src=\"gifs/mni_icbm152_t1_tal_nlin_asym_09c_plasma.gif\">\n\nThe colormap can be any colormap from the [matplotlib colormaps](https://matplotlib.org/examples/color/colormaps_reference.html).\n\n### Depth GIF\n\nTo create a depth gif, type the following command in your commandline:\n\n```\ngif_your_nifti /path/to/mni_icbm152_t1_tal_nlin_asym_09c.nii --mode depth\n```\n<img src=\"gifs/mni_icbm152_gm_tal_nlin_asym_09c_depth.gif\">\n\nThe image shows you in color what the value of the next slice will be. If the color is slightly red or blue it means that the value on the next slide is brighter or darker, respectifely. It therefore encodes a certain kind of depth into the gif.\n\n\n### RGB GIF\n\nTo create a Red Blue Green (RGB) gif, type the following command in your commandline:\n\n```\ngif_your_nifti /path/to/gm.nii /path/to/wm.nii /path/to/csf.nii --mode rgb\n```\n<img src=\"gifs/mni_icbm152_gm_tal_nlin_asym_09c_rgb.gif\">\n\nThis image takes the values from the first NIfTI file as its red colors, second NIfTI file as its green colors and third NIfTI as its blue colors.\n\n\n## Resize GIF\n\nIt is also possible to change the size of a gif, by changing the `size` parameter in any function above. The following are examples of resizing the images to 50% of it's original size, with:\n\n\n```\ngif_your_nifti /path/to/mni_icbm152_gm_tal_nlin_asym_09c.nii --size 0.5\ngif_your_nifti /path/to/mni_icbm152_gm_tal_nlin_asym_09c.nii --size 0.5 --mode pseudocolor --cmap cubehelix\ngif_your_nifti /path/to/mni_icbm152_gm_tal_nlin_asym_09c.nii --size 0.5 --mode pseudocolor --cmap inferno\ngif_your_nifti /path/to/mni_icbm152_gm_tal_nlin_asym_09c.nii --size 0.5 --mode pseudocolor --cmap viridis\n```\n\n<img src=\"gifs/mni_icbm152_gm_tal_nlin_asym_09c.gif\">\n<img src=\"gifs/mni_icbm152_gm_tal_nlin_asym_09c_cubehelix.gif\">\n<img src=\"gifs/mni_icbm152_gm_tal_nlin_asym_09c_inferno.gif\">\n<img src=\"gifs/mni_icbm152_gm_tal_nlin_asym_09c_viridis.gif\">\n\nChanging the size of a gif also changes the frames per second parameter, so that the overall tempo stays the same. Meaning, if you have a gif of original size with 20 frames per second (fps), changing the size to 50%, will cause the smaller gif to run at 10 fps, so that both take the same amount for a cycle.\n\n### Use within a python script\n\nYou can also use `gif_your_nifti` from a python script. See [script examples](examples/example_script.py) for further information.\n\n## Uploading to PyPI repository\n\nBuild the project:\n\n```shell\npython setup.py sdist\n```\n\nUpload with `twine` (`pip install twine`):\n\n```shell\ntwine upload dist/* \n```\n\nType your username and password to PyPI.\n\n### Troubleshooting with uploading to PyPI\n\nCheck, e.g., for syntax errors in the description file (README):\n\n```shell\ntwine check dist/*\n```\n\n\n\n# License\n\nThis project is licensed under [BSD 3-Clause License](LICENSE.md).\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "Create GIF from NIfTI image.",
"version": "0.0.5",
"split_keywords": [
"nifti",
"gif"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "40d883c6affbf19d9f81b3818f93cce561b4ce705325d374c3f7f63cb8b93442",
"md5": "0dbf639543f0e2fb8fc9da5ce20af688",
"sha256": "155a703226b0f9b8f730950f389ff8de7b7b30827127b00a643175deb0291db8"
},
"downloads": -1,
"filename": "nifti2gif-0.0.5.tar.gz",
"has_sig": false,
"md5_digest": "0dbf639543f0e2fb8fc9da5ce20af688",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7309,
"upload_time": "2023-01-31T12:45:00",
"upload_time_iso_8601": "2023-01-31T12:45:00.675449Z",
"url": "https://files.pythonhosted.org/packages/40/d8/83c6affbf19d9f81b3818f93cce561b4ce705325d374c3f7f63cb8b93442/nifti2gif-0.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-31 12:45:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "mikbuch",
"github_project": "nifti2gif",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "nifti2gif"
}
JSON
