README.rst 3.77 KB
Newer Older
1
2
3
fslpy
=====

Paul McCarthy's avatar
Paul McCarthy committed
4
5
.. image:: https://img.shields.io/pypi/v/fslpy.svg
   :target: https://pypi.python.org/pypi/fslpy/
6

Paul McCarthy's avatar
Paul McCarthy committed
7
8
.. image:: https://anaconda.org/conda-forge/fslpy/badges/version.svg
   :target: https://anaconda.org/conda-forge/fslpy
Paul McCarthy's avatar
Badges    
Paul McCarthy committed
9

Paul McCarthy's avatar
Paul McCarthy committed
10
11
12
.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1470750.svg
   :target: https://doi.org/10.5281/zenodo.1470750

Paul McCarthy's avatar
Badges    
Paul McCarthy committed
13
14
15
16
.. image:: https://git.fmrib.ox.ac.uk/fsl/fslpy/badges/master/coverage.svg
   :target: https://git.fmrib.ox.ac.uk/fsl/fslpy/commits/master/


17
18
The ``fslpy`` project is a `FSL <http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/>`_
programming library written in Python. It is used by `FSLeyes
Paul McCarthy's avatar
Paul McCarthy committed
19
<https://git.fmrib.ox.ac.uk/fsl/fsleyes/fsleyes/>`_.
20
21


Paul McCarthy's avatar
Paul McCarthy committed
22
``fslpy`` is tested against Python versions 3.7, 3.8, 3.9, and 3.10.
23
24


25
26
27
28
29
30
31
32
33
Installation
------------


Install ``fslpy`` and its core dependencies via pip::

    pip install fslpy


Paul McCarthy's avatar
Paul McCarthy committed
34
``fslpy`` is also available on `conda-forge <https://conda-forge.org/>`_::
35
36
37
38

    conda install -c conda-forge fslpy


39
40
41
42
Dependencies
------------


43
44
All of the core dependencies of ``fslpy`` are listed in the
`requirements.txt <requirements.txt>`_ file.
45

46
47
48
Some extra dependencies are listed in
`requirements-extra.txt <requirements-extra.txt>`_
which provide addditional functionality:
49

Paul McCarthy's avatar
Paul McCarthy committed
50
51
- ``wxPython``: The `fsl.utils.idle <fsl/utils/idle.py>`_ module has
  functionality  to schedule functions on the ``wx`` idle loop.
52

Paul McCarthy's avatar
Paul McCarthy committed
53
54
55
- ``indexed_gzip``: The `fsl.data.image.Image <fsl/data/image.py>`_ class
  can use ``indexed_gzip`` to keep large compressed images on disk instead
  of decompressing and loading them into memory..
56

Paul McCarthy's avatar
Paul McCarthy committed
57
58
59
- ``trimesh``/``rtree``: The `fsl.data.mesh.TriangleMesh <fsl/data/mesh.py>`_
  class has some methods which use ``trimesh`` to perform geometric queries
  on the mesh.
60

Paul McCarthy's avatar
Paul McCarthy committed
61
- ``Pillow``: The `fsl.data.bitmap.Bitmap <fsl/data/bitmap.py>`_ class uses
Paul McCarthy's avatar
Paul McCarthy committed
62
63
  ``Pillow`` to load image files.

64

65
If you are using Linux, you need to install wxPython first, as binaries are
Paul McCarthy's avatar
Paul McCarthy committed
66
67
not available on PyPI. Install wxPython like so, changing the URL for your
specific platform::
68

Paul McCarthy's avatar
Paul McCarthy committed
69
    pip install -f https://extras.wxpython.org/wxPython4/extras/linux/gtk2/ubuntu-16.04/ wxpython
70
71


Paul McCarthy's avatar
Paul McCarthy committed
72
73
Once wxPython has been installed, you can type the following to install the
rest of the extra dependencies::
74
75

    pip install fslpy[extras]
76
77


78
79
80
81
Dependencies for testing and documentation are listed in the
`requirements-dev.txt <requirements-dev.txt>`_ file.


82
83
84
85
Non-Python dependencies
^^^^^^^^^^^^^^^^^^^^^^^


Paul McCarthy's avatar
Paul McCarthy committed
86
87
The `fsl.data.dicom <fsl/data/dicom.py>`_ module requires the presence of
Chris Rorden's `dcm2niix <https://github.com/rordenlab/dcm2niix>`_ program.
88
89


Paul McCarthy's avatar
Paul McCarthy committed
90
91
92
93
The ``rtree`` library assumes that ``libspatialindex`` is installed on
your system.


Paul McCarthy's avatar
Paul McCarthy committed
94
95
The `fsl.transform.x5 <fsl/transform/x5.py>`_ module uses `h5py
<https://www.h5py.org/>`_, which requires ``libhdf5``.
Paul McCarthy's avatar
Paul McCarthy committed
96
97


98
99
100
Documentation
-------------

Paul McCarthy's avatar
Paul McCarthy committed
101
102
103
API documentation for ``fslpy`` is hosted at
https://open.win.ox.ac.uk/pages/fsl/fslpy/.

104
105
106
``fslpy`` is documented using `sphinx <http://http://sphinx-doc.org/>`_. You
can build the API documentation by running::

107
    pip install -r requirements-dev.txt
108
109
110
111
112
113
114
115
116
117
118
    python setup.py doc

The HTML documentation will be generated and saved in the ``doc/html/``
directory.


Tests
-----

Run the test suite via::

119
    pip install -r requirements-dev.txt
120
121
122
123
    python setup.py test

A test report will be generated at ``report.html``, and a code coverage report
will be generated in ``htmlcov/``.
Paul McCarthy's avatar
Paul McCarthy committed
124
125


Paul McCarthy's avatar
Paul McCarthy committed
126
127
128
129
130
131
132
133
Contributing
------------


If you are interested in contributing to ``fslpy``, check out the
`contributing guide <doc/contributing.rst>`_.


Paul McCarthy's avatar
Paul McCarthy committed
134
135
136
Credits
-------

137

Paul McCarthy's avatar
Paul McCarthy committed
138
The `fsl.data.dicom <fsl/data/dicom.py>`_ module is little more than a thin
Paul McCarthy's avatar
Paul McCarthy committed
139
140
wrapper around Chris Rorden's `dcm2niix
<https://github.com/rordenlab/dcm2niix>`_ program.
141
142
143
144


The `example.mgz <tests/testdata/example.mgz>`_ file, used for testing,
originates from the ``nibabel`` test data set.