| Name | wsic JSON |
| Version |
0.8.2
JSON |
| download |
| home_page | https://github.com/john-p/wsic |
| Summary | Whole Slide Image (WSI) conversion for brightfield histology images |
| upload_time | 2023-04-02 19:34:10 |
| maintainer | |
| docs_url | None |
| author | John Pocock |
| requires_python | >=3.8 |
| license | |
| keywords |
wsic
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
|
| coveralls test coverage |
No coveralls.
|
# wsic
[](https://gitmoji.dev)
[](https://github.com/psf/black)
[](https://opensource.org/licenses/MIT)
[](https://github.com/John-P/wsic/actions/workflows/python-app.yml)
[](https://wsic.readthedocs.io/en/latest/)
[](https://pypi.org/project/wsic/)
[](https://codecov.io/gh/John-P/wsic)
[](https://deepsource.io/gh/John-P/wsic/?ref=repository-badge)
Whole Slide Image (WSI) conversion for brightfield histology images.
**Note: This is in early development and there will likely be frequent
and breaking changes.**
Provides a command line interface (CLI) for easy convertion between
formats:
```bash
Usage: wsic convert [OPTIONS]
Convert a WSI.
Options:
-i, --in-path PATH Path to WSI to read from.
-o, --out-path PATH The path to output to.
-t, --tile-size <INTEGER INTEGER>...
The size of the tiles to write.
-rt, --read-tile-size <INTEGER INTEGER>...
The size of the tiles to read.
-w, --workers INTEGER The number of workers to use.
-c, --compression [blosc|deflate|jpeg xl|jpeg-ls|jpeg|jpeg2000|lzw|png|webp|zstd]
The compression to use.
-cl, --compression-level INTEGER
The compression level to use.
-d, --downsample INTEGER The downsample factor to use.
-mpp, --microns-per-pixel <FLOAT FLOAT>...
The microns per pixel to use.
-ome, --ome / --no-ome Save with OME-TIFF metadata (OME-XML).
--overwrite / --no-overwrite Whether to overwrite the output file.
-to, --timeout FLOAT Timeout in seconds for reading a tile.
-W, --writer [auto|jp2|svs|tiff|zarr]
The writer to use. Overrides writer detected
by output file extension.
-h, --help Show this message and exit.
```
## Features
- Read image data from:
- [OpenSlide](https://openslide.org/) Formats:
- Aperio SVS (.svs)
- Hamamatsu (.vms, .vmu, .ndpi)
- Leica (.scn)
- Mirax MRXS (.mrxs)
- Sakura (.svslide)
- Trestle (.tif)
- Ventana (.bif, .tif)
- Generic tiled TIFF (.tif; DEFLATE, JPEG, and Webp
compressed)
- Other Tiled TIFFs
([tifffile](https://github.com/cgohlke/tifffile) supported
formats)
- E.g. JPEG XL compressed
- [OME-TIFF](https://docs.openmicroscopy.org/ome-model/5.6.3/ome-tiff/)
(via ([tifffile](https://github.com/cgohlke/tifffile))
- [JP2](https://jpeg.org/jpeg2000/) (via
[glymur](https://glymur.readthedocs.io/en/latest/) and
[OpenJPEG](https://www.openjpeg.org/))
- [Zarr](https://zarr.readthedocs.io/en/stable/) / NGFF (single
array or pyramid group of arrays)
- [DICOM WSI](https://dicom.nema.org/dicom/dicomwsi/) (via
[wsidicom](https://github.com/imi-bigpicture/wsidicom))
- Write image data to:
- Tiled / Pyramid Generic TIFF
- OME-TIFF
- JP2
- Pyramid Zarr (NGFF)
- Custom tile size
- Compression codecs
- Lossless repackaging / transcoding (to zarr/NGFF) from:
- SVS (JPEG compressed)
- OME-TIFF (single image, JPEG and JPEG2000 (J2K) compressed)
- Generic Tiled TIFF (JPEG, JPEG2000, and WebP compressed)
- DICOM WSI (JPEG and JPEG2000 (J2K) compressed)
## Dependencies
- numpy
- zarr
- click (CLI)
### Optional Dependencies
- [OpenSlide](https://openslide.org/) and
[openslide-python](https://pypi.org/project/openslide-python/)
(reading OpenSlide Formats)
- [tifffile](https://github.com/cgohlke/tifffile) (reading tiled
TIFFs)
- [wsidicom](https://github.com/imi-bigpicture/wsidicom) (reading
DICOM WSI)
- [glymur](https://glymur.readthedocs.io/en/latest/) and
[OpenJPEG](https://www.openjpeg.org/) (reading JP2)
- [tqdm](https://github.com/tqdm/tqdm) (progress bars)
- [scipy](https://www.scipy.org/) (faster pyramid downsampling)
- [opencv-python](https://pypi.org/project/opencv-python/) (even
faster pyramid downsampling)
- [imagecodecs](https://github.com/cgohlke/imagecodecs) (additional
codecs and transcoding)
## To-Dos
For a list of To-Dos see [the project
board](https://github.com/users/John-P/projects/1/views/1).
## Other Tools
There are many other great tools in this space. Below are some other
tools for converting WSIs.
### bfconvert
Part of the Bio-Formats command line tools. Uses bioformats to convert
from many formats to OME-TIFF.
<https://www.openmicroscopy.org/bio-formats/downloads/>
### biofromats2raw
Convert from Bio-Formats formats to zarr.
<https://github.com/glencoesoftware/bioformats2raw>
### isyntax2raw
Convert from Philips' iSyntax format to a zarr.
<https://github.com/glencoesoftware/isyntax2raw>
### wsidicomiser
Convert OpenSlide images to WSI DICOM.
<https://github.com/sectra-medical/wsidicomizer>
## Credits
This package was created with
[Cookiecutter](https://github.com/audreyr/cookiecutter) and the
[audreyr/cookiecutter-pypackage](https://github.com/audreyr/cookiecutter-pypackage)
project template.
# History
## 0.8.0 (2023-04-01)
- Add DICOM writer.
- Avoid decoding entire TIFF before conversion starts.
- TIFFReader can now expose a dask array view (using tiffile Zarr view
underneath).
- Add overwrite option to transcode CLI mode.
- Refactor to use persistent worker subprocesses. This avoids recreating
the reader object for each region read. For some reader such as
DICOMWSIReader this significantly improves performance.
- General refactoring and code cleanup.
- Bug fixes:
- Fix writing MPP for SVSWriter.
- Remove OpenSlide thumbnail generation method. This would cause the
process to run out of memory for some files and the base
implementation works just as well without this memory issue.
## 0.7.0 (2022-12-15)
- Normalise TIFF array axes (to YXC order) when reading using tiffile.
- Bug fixes:
- Fix reading/writing JP2 resoluion metadata (vres/hres are in m not
cm).
- Join child processes when finishing writing / exiting.
- Copy the reader tile size for transcode mode.
- Return None for MPP when JP2 has no resolution box.
- Set resolution units to cm when writing TIFFs.
- Use the MPP from the reader when writing JP2.
- Add a zarr intermediate for JP2 writing (allows different read and
write tile sizes).
## 0.6.1 (2022-10-21)
- Select Writer class based on file extension from CLI.
- Bug fixes:
- Fix writing MPP to NGFF v0.4.
- Change coordinate transformation ordering.
- Fix reading TIFF resolution tag. Previously only the numerator of
the resolution fraction was being read.
- Other minor bug fixes.
## 0.6.0 (2022-10-03)
- Add ability to write resolution metadata to JP2. Thanks to
@quintusdias for helping get this implemented in glymur.
- Remove QOI codec code as this is not included in imagecodes. Thanks to
Christoph Gohlke for adding this.
- Add a "How do I?" documentation page.
## 0.5.1 (2022-06-27)
- Bug fixes:
- Fix parsing of OpenSlide MPP to float.
## 0.5.0 (2022-06-25)
- Add ability to transcode/repackage to a TIFF file (from DICOM or SVS).
- Refactor `ZarrReaderWriter` to seperate `ZarrWriter` and `ZarrReader`.
- Bug fixes:
- Fix thumbnaiul generation for zarr.
- Fix NGFF metadata `CoordinateTransformation` field default factor.
## 0.4.0 (2022-06-20)
- Add ability to write JPEG compressed SVS files.
- Add support for thumbnail generation and a CLI command.
- Swap from strings to enums for codecs and color spaces.
## 0.3.0 (2022-05-13)
- Remove unused CLI debug option.
- Add generation of OME-NGFF metadata (JSON .zattrs file).
- Add timeout when copying tiles to prevent indefinite hanging.
- Improve joining/termination of child processes at shutdown.
- Use the TIFF resolution tag if present.
- Add `get_tile` method to all `Reader` classes.
- Update supported Python versions to 3.8, 3.9, 3.10.
- Bug fixes:
- Fix and issue with concatenation of pyramid downsamples.
- Add a custom Queue class for multiprocessing on macOS.
- Fix handling of `pyramid_downsamples` argument when `None`.
## 0.2.0 (2022-03-22)
- Add Support To Read DICOM WSI and transform to zarr.
## 0.1.0 (2022-02-22)
- First release on PyPI.
Raw data
{
"_id": null,
"home_page": "https://github.com/john-p/wsic",
"name": "wsic",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "wsic",
"author": "John Pocock",
"author_email": "j.c.pocock@warwick.ac.uk",
"download_url": "https://files.pythonhosted.org/packages/1e/50/1bc6edc89301556ac5f9d226c2a1982b6c1c6d6f50535f926103332d4fda/wsic-0.8.2.tar.gz",
"platform": null,
"description": "# wsic\n\n[](https://gitmoji.dev)\n[](https://github.com/psf/black)\n[](https://opensource.org/licenses/MIT)\n\n[](https://github.com/John-P/wsic/actions/workflows/python-app.yml)\n[](https://wsic.readthedocs.io/en/latest/)\n\n[](https://pypi.org/project/wsic/)\n[](https://codecov.io/gh/John-P/wsic)\n[](https://deepsource.io/gh/John-P/wsic/?ref=repository-badge)\n\nWhole Slide Image (WSI) conversion for brightfield histology images.\n\n**Note: This is in early development and there will likely be frequent\nand breaking changes.**\n\nProvides a command line interface (CLI) for easy convertion between\nformats:\n\n```bash\nUsage: wsic convert [OPTIONS]\n\n Convert a WSI.\n\nOptions:\n -i, --in-path PATH Path to WSI to read from.\n -o, --out-path PATH The path to output to.\n -t, --tile-size <INTEGER INTEGER>...\n The size of the tiles to write.\n -rt, --read-tile-size <INTEGER INTEGER>...\n The size of the tiles to read.\n -w, --workers INTEGER The number of workers to use.\n -c, --compression [blosc|deflate|jpeg xl|jpeg-ls|jpeg|jpeg2000|lzw|png|webp|zstd]\n The compression to use.\n -cl, --compression-level INTEGER\n The compression level to use.\n -d, --downsample INTEGER The downsample factor to use.\n -mpp, --microns-per-pixel <FLOAT FLOAT>...\n The microns per pixel to use.\n -ome, --ome / --no-ome Save with OME-TIFF metadata (OME-XML).\n --overwrite / --no-overwrite Whether to overwrite the output file.\n -to, --timeout FLOAT Timeout in seconds for reading a tile.\n -W, --writer [auto|jp2|svs|tiff|zarr]\n The writer to use. Overrides writer detected\n by output file extension.\n -h, --help Show this message and exit.\n```\n\n\n\n## Features\n\n- Read image data from:\n - [OpenSlide](https://openslide.org/) Formats:\n - Aperio SVS (.svs)\n - Hamamatsu (.vms, .vmu, .ndpi)\n - Leica (.scn)\n - Mirax MRXS (.mrxs)\n - Sakura (.svslide)\n - Trestle (.tif)\n - Ventana (.bif, .tif)\n - Generic tiled TIFF (.tif; DEFLATE, JPEG, and Webp\n compressed)\n - Other Tiled TIFFs\n ([tifffile](https://github.com/cgohlke/tifffile) supported\n formats)\n - E.g. JPEG XL compressed\n - [OME-TIFF](https://docs.openmicroscopy.org/ome-model/5.6.3/ome-tiff/)\n (via ([tifffile](https://github.com/cgohlke/tifffile))\n - [JP2](https://jpeg.org/jpeg2000/) (via\n [glymur](https://glymur.readthedocs.io/en/latest/) and\n [OpenJPEG](https://www.openjpeg.org/))\n - [Zarr](https://zarr.readthedocs.io/en/stable/) / NGFF (single\n array or pyramid group of arrays)\n - [DICOM WSI](https://dicom.nema.org/dicom/dicomwsi/) (via\n [wsidicom](https://github.com/imi-bigpicture/wsidicom))\n- Write image data to:\n - Tiled / Pyramid Generic TIFF\n - OME-TIFF\n - JP2\n - Pyramid Zarr (NGFF)\n- Custom tile size\n- Compression codecs\n- Lossless repackaging / transcoding (to zarr/NGFF) from:\n - SVS (JPEG compressed)\n - OME-TIFF (single image, JPEG and JPEG2000 (J2K) compressed)\n - Generic Tiled TIFF (JPEG, JPEG2000, and WebP compressed)\n - DICOM WSI (JPEG and JPEG2000 (J2K) compressed)\n\n## Dependencies\n\n- numpy\n- zarr\n- click (CLI)\n\n### Optional Dependencies\n\n- [OpenSlide](https://openslide.org/) and\n [openslide-python](https://pypi.org/project/openslide-python/)\n (reading OpenSlide Formats)\n- [tifffile](https://github.com/cgohlke/tifffile) (reading tiled\n TIFFs)\n- [wsidicom](https://github.com/imi-bigpicture/wsidicom) (reading\n DICOM WSI)\n- [glymur](https://glymur.readthedocs.io/en/latest/) and\n [OpenJPEG](https://www.openjpeg.org/) (reading JP2)\n- [tqdm](https://github.com/tqdm/tqdm) (progress bars)\n- [scipy](https://www.scipy.org/) (faster pyramid downsampling)\n- [opencv-python](https://pypi.org/project/opencv-python/) (even\n faster pyramid downsampling)\n- [imagecodecs](https://github.com/cgohlke/imagecodecs) (additional\n codecs and transcoding)\n\n## To-Dos\n\nFor a list of To-Dos see [the project\nboard](https://github.com/users/John-P/projects/1/views/1).\n\n## Other Tools\n\nThere are many other great tools in this space. Below are some other\ntools for converting WSIs.\n\n### bfconvert\n\nPart of the Bio-Formats command line tools. Uses bioformats to convert\nfrom many formats to OME-TIFF.\n\n<https://www.openmicroscopy.org/bio-formats/downloads/>\n\n### biofromats2raw\n\nConvert from Bio-Formats formats to zarr.\n\n<https://github.com/glencoesoftware/bioformats2raw>\n\n### isyntax2raw\n\nConvert from Philips' iSyntax format to a zarr.\n\n<https://github.com/glencoesoftware/isyntax2raw>\n\n### wsidicomiser\n\nConvert OpenSlide images to WSI DICOM.\n\n<https://github.com/sectra-medical/wsidicomizer>\n\n## Credits\n\nThis package was created with\n[Cookiecutter](https://github.com/audreyr/cookiecutter) and the\n[audreyr/cookiecutter-pypackage](https://github.com/audreyr/cookiecutter-pypackage)\nproject template.\n\n\n# History\n\n## 0.8.0 (2023-04-01)\n\n- Add DICOM writer.\n- Avoid decoding entire TIFF before conversion starts.\n- TIFFReader can now expose a dask array view (using tiffile Zarr view\n underneath).\n- Add overwrite option to transcode CLI mode.\n- Refactor to use persistent worker subprocesses. This avoids recreating\n the reader object for each region read. For some reader such as\n DICOMWSIReader this significantly improves performance.\n- General refactoring and code cleanup.\n- Bug fixes:\n - Fix writing MPP for SVSWriter.\n - Remove OpenSlide thumbnail generation method. This would cause the\n process to run out of memory for some files and the base\n implementation works just as well without this memory issue.\n\n## 0.7.0 (2022-12-15)\n\n- Normalise TIFF array axes (to YXC order) when reading using tiffile.\n- Bug fixes:\n - Fix reading/writing JP2 resoluion metadata (vres/hres are in m not\n cm).\n - Join child processes when finishing writing / exiting.\n - Copy the reader tile size for transcode mode.\n - Return None for MPP when JP2 has no resolution box.\n - Set resolution units to cm when writing TIFFs.\n - Use the MPP from the reader when writing JP2.\n - Add a zarr intermediate for JP2 writing (allows different read and\n write tile sizes).\n\n## 0.6.1 (2022-10-21)\n\n- Select Writer class based on file extension from CLI.\n- Bug fixes:\n - Fix writing MPP to NGFF v0.4.\n - Change coordinate transformation ordering.\n - Fix reading TIFF resolution tag. Previously only the numerator of\n the resolution fraction was being read.\n - Other minor bug fixes.\n\n## 0.6.0 (2022-10-03)\n\n- Add ability to write resolution metadata to JP2. Thanks to\n @quintusdias for helping get this implemented in glymur.\n- Remove QOI codec code as this is not included in imagecodes. Thanks to\n Christoph Gohlke for adding this.\n- Add a \"How do I?\" documentation page.\n\n## 0.5.1 (2022-06-27)\n\n- Bug fixes:\n - Fix parsing of OpenSlide MPP to float.\n\n## 0.5.0 (2022-06-25)\n\n- Add ability to transcode/repackage to a TIFF file (from DICOM or SVS).\n- Refactor `ZarrReaderWriter` to seperate `ZarrWriter` and `ZarrReader`.\n- Bug fixes:\n - Fix thumbnaiul generation for zarr.\n - Fix NGFF metadata `CoordinateTransformation` field default factor.\n\n## 0.4.0 (2022-06-20)\n\n- Add ability to write JPEG compressed SVS files.\n- Add support for thumbnail generation and a CLI command.\n- Swap from strings to enums for codecs and color spaces.\n\n## 0.3.0 (2022-05-13)\n\n- Remove unused CLI debug option.\n- Add generation of OME-NGFF metadata (JSON .zattrs file).\n- Add timeout when copying tiles to prevent indefinite hanging.\n- Improve joining/termination of child processes at shutdown.\n- Use the TIFF resolution tag if present.\n- Add `get_tile` method to all `Reader` classes.\n- Update supported Python versions to 3.8, 3.9, 3.10.\n- Bug fixes:\n - Fix and issue with concatenation of pyramid downsamples.\n - Add a custom Queue class for multiprocessing on macOS.\n - Fix handling of `pyramid_downsamples` argument when `None`.\n\n## 0.2.0 (2022-03-22)\n\n- Add Support To Read DICOM WSI and transform to zarr.\n\n## 0.1.0 (2022-02-22)\n\n- First release on PyPI.\n",
"bugtrack_url": null,
"license": "",
"summary": "Whole Slide Image (WSI) conversion for brightfield histology images",
"version": "0.8.2",
"split_keywords": [
"wsic"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ebc1339e65a9d52c0b2db0285d0f791a2b513c32bfcb410faa4b75e904387e29",
"md5": "98eea44848f0929a19714fb51d722cdc",
"sha256": "0a6a5418195cf82587c10fd0b5cb9833fb4cf40b6a49a492ec23c595639c6981"
},
"downloads": -1,
"filename": "wsic-0.8.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "98eea44848f0929a19714fb51d722cdc",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 115741,
"upload_time": "2023-04-02T19:34:07",
"upload_time_iso_8601": "2023-04-02T19:34:07.613378Z",
"url": "https://files.pythonhosted.org/packages/eb/c1/339e65a9d52c0b2db0285d0f791a2b513c32bfcb410faa4b75e904387e29/wsic-0.8.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1e501bc6edc89301556ac5f9d226c2a1982b6c1c6d6f50535f926103332d4fda",
"md5": "58ef66336b26dbc624d8e3c34d8ef53e",
"sha256": "e80d0c439f651edf8f83c2eed32f8c64561a803923860fc31734a35d22003d47"
},
"downloads": -1,
"filename": "wsic-0.8.2.tar.gz",
"has_sig": false,
"md5_digest": "58ef66336b26dbc624d8e3c34d8ef53e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 22179947,
"upload_time": "2023-04-02T19:34:10",
"upload_time_iso_8601": "2023-04-02T19:34:10.268633Z",
"url": "https://files.pythonhosted.org/packages/1e/50/1bc6edc89301556ac5f9d226c2a1982b6c1c6d6f50535f926103332d4fda/wsic-0.8.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-02 19:34:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "john-p",
"github_project": "wsic",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "wsic"
}
