<p align="center">
<a href="https://github.com/pydicom/pylibjpeg/actions?query=workflow%3Aunit-tests"><img alt="Build status" src="https://github.com/pydicom/pylibjpeg/workflows/unit-tests/badge.svg"></a>
<a href="https://codecov.io/gh/pydicom/pylibjpeg"><img alt="Test coverage" src="https://codecov.io/gh/pydicom/pylibjpeg/branch/main/graph/badge.svg"></a>
<a href="https://pypi.org/project/pylibjpeg/"><img alt="PyPI versions" src="https://img.shields.io/pypi/v/pylibjpeg"></a>
<a href="https://www.python.org/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/pylibjpeg.svg"></a>
<a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
</p>
## pylibjpeg
A Python 3.8+ framework for decoding JPEG images and decoding/encoding RLE datasets, with a focus on providing support for [pydicom](https://github.com/pydicom/pydicom).
### Installation
#### Installing the current release
```
pip install pylibjpeg
```
##### Installing extra requirements
The package can be installed with extra requirements to enable support for JPEG (with `libjpeg`), JPEG 2000 (with `openjpeg`) and Run-Length Encoding (RLE) (with `rle`), respectively:
```
pip install pylibjpeg[libjpeg,openjpeg,rle]
```
Or alternatively with just `all`:
```
pip install pylibjpeg[all]
```
#### Installing the development version
Make sure [Git](https://git-scm.com/) is installed, then
```bash
git clone https://github.com/pydicom/pylibjpeg
python -m pip install pylibjpeg
```
### Plugins
One or more plugins are required before *pylibjpeg* is able to handle JPEG images or RLE datasets. To handle a given format or DICOM Transfer Syntax
you first have to install the corresponding package:
#### Supported Image Formats
|Format |Decode?|Encode?|Plugin | License |Based on |
|--- |------ |--- |--- |--- |--- |
|JPEG, JPEG-LS and JPEG XT|Yes |No |[pylibjpeg-libjpeg][1] | GPLv3 |[libjpeg][2] |
|JPEG 2000 |Yes |Yes |[pylibjpeg-openjpeg][3]| MIT |[openjpeg][4]|
|RLE Lossless (PackBits) |Yes |Yes |[pylibjpeg-rle][5] | MIT |- |
#### Supported DICOM Transfer Syntaxes
|UID | Description | Plugin |
|--- |--- |---- |
|1.2.840.10008.1.2.4.50 |JPEG Baseline (Process 1) |[pylibjpeg-libjpeg][1] |
|1.2.840.10008.1.2.4.51 |JPEG Extended (Process 2 and 4) |[pylibjpeg-libjpeg][1] |
|1.2.840.10008.1.2.4.57 |JPEG Lossless, Non-Hierarchical (Process 14) |[pylibjpeg-libjpeg][1] |
|1.2.840.10008.1.2.4.70 |JPEG Lossless, Non-Hierarchical, First-Order Prediction</br>(Process 14, Selection Value 1) | [pylibjpeg-libjpeg][1]|
|1.2.840.10008.1.2.4.80 |JPEG-LS Lossless |[pylibjpeg-libjpeg][1] |
|1.2.840.10008.1.2.4.81 |JPEG-LS Lossy (Near-Lossless) Image Compression |[pylibjpeg-libjpeg][1] |
|1.2.840.10008.1.2.4.90 |JPEG 2000 Image Compression (Lossless Only) |[pylibjpeg-openjpeg][3]|
|1.2.840.10008.1.2.4.91 |JPEG 2000 Image Compression |[pylibjpeg-openjpeg][3]|
|1.2.840.10008.1.2.4.201|High-Throughput JPEG 2000 Image Compression (Lossless Only) |[pylibjpeg-openjpeg][3]|
|1.2.840.10008.1.2.4.202|High-Throughput JPEG 2000 with RPCL Options Image Compression (Lossless Only) |[pylibjpeg-openjpeg][3]|
|1.2.840.10008.1.2.4.203|High-Throughput JPEG 2000 Image Compression |[pylibjpeg-openjpeg][3]|
|1.2.840.10008.1.2.5 |RLE Lossless |[pylibjpeg-rle][5] |
If you're not sure what the dataset's *Transfer Syntax UID* is, it can be
determined with:
```python
>>> from pydicom import dcmread
>>> ds = dcmread('path/to/dicom_file')
>>> ds.file_meta.TransferSyntaxUID.name
```
[1]: https://github.com/pydicom/pylibjpeg-libjpeg
[2]: https://github.com/thorfdbg/libjpeg
[3]: https://github.com/pydicom/pylibjpeg-openjpeg
[4]: https://github.com/uclouvain/openjpeg
[5]: https://github.com/pydicom/pylibjpeg-rle
### Usage
#### Decoding
##### With pydicom
Assuming you have *pydicom* v2.1+ and suitable plugins installed:
```python
from pydicom import dcmread
from pydicom.data import get_testdata_file
# With the pylibjpeg-libjpeg plugin
ds = dcmread(get_testdata_file('JPEG-LL.dcm'))
jpg_arr = ds.pixel_array
# With the pylibjpeg-openjpeg plugin
ds = dcmread(get_testdata_file('JPEG2000.dcm'))
j2k_arr = ds.pixel_array
# With the pylibjpeg-rle plugin and pydicom v2.2+
ds = dcmread(get_testdata_file('OBXXXX1A_rle.dcm'))
# pydicom defaults to the numpy handler for RLE so need
# to explicitly specify the use of pylibjpeg
ds.decompress("pylibjpeg")
rle_arr = ds.pixel_array
```
##### Standalone JPEG decoding
You can also just use *pylibjpeg* to decode JPEG images to a [numpy ndarray](https://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html), provided you have a suitable plugin installed:
```python
from pylibjpeg import decode
# Can decode using the path to a JPG file as str or path-like
arr = decode('filename.jpg')
# Or a file-like...
with open('filename.jpg', 'rb') as f:
arr = decode(f)
# Or bytes...
with open('filename.jpg', 'rb') as f:
arr = decode(f.read())
```
#### Encoding
##### With pydicom
Assuming you have *pydicom* v2.2+ and suitable plugins installed:
```python
from pydicom import dcmread
from pydicom.data import get_testdata_file
from pydicom.uid import RLELossless
ds = dcmread(get_testdata_file("CT_small.dcm"))
# Encode in-place using RLE Lossless and update the dataset
# Updates the Pixel Data, Transfer Syntax UID and Planar Configuration
ds.compress(RLELossless)
# Save compressed
ds.save_as("CT_small_rle.dcm")
```
Raw data
{
"_id": null,
"home_page": null,
"name": "pylibjpeg",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "dicom pydicom python imaging jpg jpeg jpg-ls jpeg-ls jpeg2k jpeg2000 rle",
"author": "pylibjpeg contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/7c/65/34b3da5d0f8fabf09f2f8d5db2977e307d0aa2cdba6c605338005e91077d/pylibjpeg-2.0.1.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n<a href=\"https://github.com/pydicom/pylibjpeg/actions?query=workflow%3Aunit-tests\"><img alt=\"Build status\" src=\"https://github.com/pydicom/pylibjpeg/workflows/unit-tests/badge.svg\"></a>\n<a href=\"https://codecov.io/gh/pydicom/pylibjpeg\"><img alt=\"Test coverage\" src=\"https://codecov.io/gh/pydicom/pylibjpeg/branch/main/graph/badge.svg\"></a>\n<a href=\"https://pypi.org/project/pylibjpeg/\"><img alt=\"PyPI versions\" src=\"https://img.shields.io/pypi/v/pylibjpeg\"></a>\n<a href=\"https://www.python.org/\"><img alt=\"Python versions\" src=\"https://img.shields.io/pypi/pyversions/pylibjpeg.svg\"></a>\n<a href=\"https://github.com/psf/black\"><img alt=\"Code style: black\" src=\"https://img.shields.io/badge/code%20style-black-000000.svg\"></a>\n</p>\n\n## pylibjpeg\n\nA Python 3.8+ framework for decoding JPEG images and decoding/encoding RLE datasets, with a focus on providing support for [pydicom](https://github.com/pydicom/pydicom).\n\n\n### Installation\n#### Installing the current release\n\n```\npip install pylibjpeg\n```\n\n##### Installing extra requirements\n\nThe package can be installed with extra requirements to enable support for JPEG (with `libjpeg`), JPEG 2000 (with `openjpeg`) and Run-Length Encoding (RLE) (with `rle`), respectively:\n\n```\npip install pylibjpeg[libjpeg,openjpeg,rle]\n```\n\nOr alternatively with just `all`:\n\n```\npip install pylibjpeg[all]\n```\n\n#### Installing the development version\n\nMake sure [Git](https://git-scm.com/) is installed, then\n```bash\ngit clone https://github.com/pydicom/pylibjpeg\npython -m pip install pylibjpeg\n```\n\n### Plugins\n\nOne or more plugins are required before *pylibjpeg* is able to handle JPEG images or RLE datasets. To handle a given format or DICOM Transfer Syntax\nyou first have to install the corresponding package:\n\n#### Supported Image Formats\n|Format |Decode?|Encode?|Plugin | License |Based on |\n|--- |------ |--- |--- |--- |--- |\n|JPEG, JPEG-LS and JPEG XT|Yes |No |[pylibjpeg-libjpeg][1] | GPLv3 |[libjpeg][2] |\n|JPEG 2000 |Yes |Yes |[pylibjpeg-openjpeg][3]| MIT |[openjpeg][4]|\n|RLE Lossless (PackBits) |Yes |Yes |[pylibjpeg-rle][5] | MIT |- |\n\n#### Supported DICOM Transfer Syntaxes\n\n|UID | Description | Plugin |\n|--- |--- |---- |\n|1.2.840.10008.1.2.4.50 |JPEG Baseline (Process 1) |[pylibjpeg-libjpeg][1] |\n|1.2.840.10008.1.2.4.51 |JPEG Extended (Process 2 and 4) |[pylibjpeg-libjpeg][1] |\n|1.2.840.10008.1.2.4.57 |JPEG Lossless, Non-Hierarchical (Process 14) |[pylibjpeg-libjpeg][1] |\n|1.2.840.10008.1.2.4.70 |JPEG Lossless, Non-Hierarchical, First-Order Prediction</br>(Process 14, Selection Value 1) | [pylibjpeg-libjpeg][1]|\n|1.2.840.10008.1.2.4.80 |JPEG-LS Lossless |[pylibjpeg-libjpeg][1] |\n|1.2.840.10008.1.2.4.81 |JPEG-LS Lossy (Near-Lossless) Image Compression |[pylibjpeg-libjpeg][1] |\n|1.2.840.10008.1.2.4.90 |JPEG 2000 Image Compression (Lossless Only) |[pylibjpeg-openjpeg][3]|\n|1.2.840.10008.1.2.4.91 |JPEG 2000 Image Compression |[pylibjpeg-openjpeg][3]|\n|1.2.840.10008.1.2.4.201|High-Throughput JPEG 2000 Image Compression (Lossless Only) |[pylibjpeg-openjpeg][3]|\n|1.2.840.10008.1.2.4.202|High-Throughput JPEG 2000 with RPCL Options Image Compression (Lossless Only) |[pylibjpeg-openjpeg][3]|\n|1.2.840.10008.1.2.4.203|High-Throughput JPEG 2000 Image Compression |[pylibjpeg-openjpeg][3]|\n|1.2.840.10008.1.2.5 |RLE Lossless |[pylibjpeg-rle][5] |\n\nIf you're not sure what the dataset's *Transfer Syntax UID* is, it can be\ndetermined with:\n```python\n>>> from pydicom import dcmread\n>>> ds = dcmread('path/to/dicom_file')\n>>> ds.file_meta.TransferSyntaxUID.name\n```\n\n[1]: https://github.com/pydicom/pylibjpeg-libjpeg\n[2]: https://github.com/thorfdbg/libjpeg\n[3]: https://github.com/pydicom/pylibjpeg-openjpeg\n[4]: https://github.com/uclouvain/openjpeg\n[5]: https://github.com/pydicom/pylibjpeg-rle\n\n\n### Usage\n#### Decoding\n##### With pydicom\nAssuming you have *pydicom* v2.1+ and suitable plugins installed:\n\n```python\nfrom pydicom import dcmread\nfrom pydicom.data import get_testdata_file\n\n# With the pylibjpeg-libjpeg plugin\nds = dcmread(get_testdata_file('JPEG-LL.dcm'))\njpg_arr = ds.pixel_array\n\n# With the pylibjpeg-openjpeg plugin\nds = dcmread(get_testdata_file('JPEG2000.dcm'))\nj2k_arr = ds.pixel_array\n\n# With the pylibjpeg-rle plugin and pydicom v2.2+\nds = dcmread(get_testdata_file('OBXXXX1A_rle.dcm'))\n# pydicom defaults to the numpy handler for RLE so need\n# to explicitly specify the use of pylibjpeg\nds.decompress(\"pylibjpeg\")\nrle_arr = ds.pixel_array\n```\n\n##### Standalone JPEG decoding\nYou can also just use *pylibjpeg* to decode JPEG images to a [numpy ndarray](https://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html), provided you have a suitable plugin installed:\n```python\nfrom pylibjpeg import decode\n\n# Can decode using the path to a JPG file as str or path-like\narr = decode('filename.jpg')\n\n# Or a file-like...\nwith open('filename.jpg', 'rb') as f:\n arr = decode(f)\n\n# Or bytes...\nwith open('filename.jpg', 'rb') as f:\n arr = decode(f.read())\n```\n\n#### Encoding\n##### With pydicom\n\nAssuming you have *pydicom* v2.2+ and suitable plugins installed:\n\n```python\nfrom pydicom import dcmread\nfrom pydicom.data import get_testdata_file\nfrom pydicom.uid import RLELossless\n\nds = dcmread(get_testdata_file(\"CT_small.dcm\"))\n\n# Encode in-place using RLE Lossless and update the dataset\n# Updates the Pixel Data, Transfer Syntax UID and Planar Configuration\nds.compress(RLELossless)\n\n# Save compressed\nds.save_as(\"CT_small_rle.dcm\")\n```\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python framework for decoding JPEG and decoding/encoding DICOM RLE data, with a focus on supporting pydicom",
"version": "2.0.1",
"project_urls": {
"download": "https://github.com/pydicom/pylibjpeg/archive/main.zip",
"homepage": "https://github.com/pydicom/pylibjpeg",
"repository": "https://github.com/pydicom/pylibjpeg"
},
"split_keywords": [
"dicom",
"pydicom",
"python",
"imaging",
"jpg",
"jpeg",
"jpg-ls",
"jpeg-ls",
"jpeg2k",
"jpeg2000",
"rle"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1fab8181a9ddcca65487f9f0e9054da7675ecc701fca29904c7d9d44fa8789a7",
"md5": "c74c3ad4585d3bbd1920d83c428c9afe",
"sha256": "90b611304c99b0752c0e0d78d3c3c25ea0b1a53c82e40c78f347367a8709edcc"
},
"downloads": -1,
"filename": "pylibjpeg-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c74c3ad4585d3bbd1920d83c428c9afe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 24562,
"upload_time": "2024-06-17T03:07:19",
"upload_time_iso_8601": "2024-06-17T03:07:19.106948Z",
"url": "https://files.pythonhosted.org/packages/1f/ab/8181a9ddcca65487f9f0e9054da7675ecc701fca29904c7d9d44fa8789a7/pylibjpeg-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7c6534b3da5d0f8fabf09f2f8d5db2977e307d0aa2cdba6c605338005e91077d",
"md5": "cd24db648eb1a5f84ddbe297735785db",
"sha256": "3beae5cf829f83bf0c1e5640c3b655bc0f406b8be302215e72f8d31a4185a947"
},
"downloads": -1,
"filename": "pylibjpeg-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "cd24db648eb1a5f84ddbe297735785db",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 21314,
"upload_time": "2024-06-17T03:07:20",
"upload_time_iso_8601": "2024-06-17T03:07:20.482382Z",
"url": "https://files.pythonhosted.org/packages/7c/65/34b3da5d0f8fabf09f2f8d5db2977e307d0aa2cdba6c605338005e91077d/pylibjpeg-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-17 03:07:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pydicom",
"github_project": "pylibjpeg",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "pylibjpeg"
}
JSON
