|
5 | 5 | [](https://raw.githubusercontent.com/AdaptiveParticles/pyapr/master/LICENSE) |
6 | 6 | []((https://python.org)) |
7 | 7 | [](https://pypi.org/project/pyapr/) |
8 | | - |
9 | | -[](https://zenodo.org/badge/latestdoi/184399854) |
| 8 | +[](https://pepy.tech/project/pyapr) |
| 9 | +[](https://doi.org/10.5281/zenodo.7304045) |
10 | 10 |
|
11 | 11 | Documentation can be found [here](https://adaptiveparticles.github.io/pyapr/index.html). |
12 | 12 |
|
13 | | -Content-adaptive storage and processing of large volumetric microscopy data using |
14 | | -the Adaptive Particle Representation (APR). |
| 13 | +Content-adaptive storage and processing of large volumetric microscopy data using the Adaptive Particle Representation (APR). |
| 14 | + |
| 15 | +The APR is an adaptive image representation designed primarily for large 3D fluorescence microscopy datasets. By replacing pixels with particles positioned according to the image content, it enables orders-of-magnitude compression of sparse image data while maintaining image quality. However, unlike most compression formats, the APR can be used directly in a wide range of processing tasks - even on the GPU! |
| 16 | + |
| 17 | +| Pixels | APR | |
| 18 | +| :--: | :--: | |
| 19 | +|  |  | |
| 20 | +| Uniform sampling | Adaptive sampling | |
| 21 | + |
| 22 | +*[image source](https://bbbc.broadinstitute.org/bbbc/BBBC032), |
| 23 | +[illustration source](https://ieeexplore.ieee.org/abstract/document/9796006)* |
15 | 24 |
|
16 | | -The APR is an adaptive image representation designed primarily for large 3D fluorescence |
17 | | -microscopy datasets. By replacing pixels with particles positioned according to the |
18 | | -image content, it enables orders-of-magnitude compression of sparse image data |
19 | | -while maintaining image quality. However, unlike most compression formats, the APR |
20 | | -can be used directly in a wide range of processing tasks - even on the GPU! |
21 | 25 |
|
22 | 26 | For more detailed information about the APR and its use, see: |
23 | 27 | - [Adaptive particle representation of fluorescence microscopy images](https://www.nature.com/articles/s41467-018-07390-9) (nature communications) |
24 | 28 | - [Parallel Discrete Convolutions on Adaptive Particle Representations of Images](https://ieeexplore.ieee.org/abstract/document/9796006) (IEEE Transactions on Image Processing) |
25 | 29 |
|
26 | 30 | **pyapr** is built on top of the C++ library [LibAPR] using [pybind11]. |
27 | 31 |
|
28 | | -## Installation |
29 | | -For Windows 10, OSX, and Linux and Python versions 3.7-3.9 direct installation with OpenMP support should work via [pip]: |
| 32 | +## Quick start guide |
| 33 | + |
| 34 | +Convert images to APR using minimal amounts of code (*see [get_apr_demo](demo/get_apr_demo.py) and [get_apr_interactive_demo](demo/get_apr_interactive_demo.py) for additional options*). |
| 35 | + |
| 36 | +```python |
| 37 | +import pyapr |
| 38 | +from skimage import io |
| 39 | + |
| 40 | +# read image into numpy array |
| 41 | +img = io.imread('my_image.tif') |
| 42 | + |
| 43 | +# convert to APR using default settings |
| 44 | +apr, parts = pyapr.converter.get_apr(img) |
| 45 | + |
| 46 | +# write APR to file |
| 47 | +pyapr.io.write('my_image.apr', apr, parts) |
30 | 48 | ``` |
31 | | -pip install pyapr |
| 49 | + |
| 50 | + |
| 51 | + |
| 52 | +To return to the pixel representation: |
| 53 | +```python |
| 54 | +# reconstruct pixel image |
| 55 | +img = pyapr.reconstruction.reconstruct_constant(apr, parts) |
32 | 56 | ``` |
33 | | -Note: Due to the use of OpenMP, it is encouraged to install as part of a virtualenv. |
34 | 57 |
|
35 | | -See [INSTALL] for manual build instructions. |
36 | 58 |
|
37 | | -## Exclusive features |
| 59 | +Inspect APRs using our makeshift image viewers (*see [napari-apr-viewer] for less experimental visualization options*). |
| 60 | + |
| 61 | +```python |
| 62 | +# read APR from file |
| 63 | +apr, parts = pyapr.io.read('my_image.apr') |
38 | 64 |
|
39 | | -In addition to providing wrappers for most of the functionality of LibAPR, we provide a number of |
40 | | -new features that simplify the generation and handling of the APR. For example: |
| 65 | +# launch viewer |
| 66 | +pyapr.viewer.parts_viewer(apr, parts) |
| 67 | +``` |
| 68 | + |
41 | 69 |
|
42 | | -* Interactive APR conversion (see [get_apr_interactive_demo](demo/get_apr_interactive_demo.py) and |
43 | | - [get_apr_by_block_interactive_demo](demo/get_apr_by_block_interactive_demo.py)) |
44 | | -* Interactive APR z-slice viewer (see [viewer_demo](demo/viewer_demo.py)) |
45 | | -* Interactive APR raycast (maximum intensity projection) viewer (see [raycast_demo](demo/raycast_demo.py)) |
46 | | -* Interactive lossy compression of particle intensities (see [compress_particles_demo](demo/compress_particles_demo.py)) |
| 70 | +The `View Level` toggle allows you to see the adaptation (brighter = higher resolution). |
47 | 71 |
|
48 | | -For further examples see the [demo scripts]. |
| 72 | + |
49 | 73 |
|
50 | | -Also be sure to check out our (experimental) [napari] plugin: [napari-apr-viewer]. |
| 74 | +Or view the result in 3D using APR-native maximum intensity projection raycast (cpu). |
| 75 | +```python |
| 76 | +# launch raycast viewer |
| 77 | +pyapr.viewer.raycast_viewer(apr, parts) |
| 78 | +``` |
| 79 | + |
| 80 | + |
| 81 | +See the [demo scripts] for more examples. |
| 82 | + |
| 83 | +## Installation |
| 84 | +For Windows 10, OSX, and Linux direct installation with OpenMP support should work via [pip]: |
| 85 | +``` |
| 86 | +pip install pyapr |
| 87 | +``` |
| 88 | +Note: Due to the use of OpenMP, it is encouraged to install as part of a virtualenv. |
| 89 | + |
| 90 | +See [INSTALL] for manual build instructions. |
51 | 91 |
|
52 | 92 |
|
53 | 93 | ## License |
|
0 commit comments