*********************
Large Image Converter
*********************
Convert a variety of images into the most efficient format for Large Image.
Geospatial files are converted into cloud-optimized geotiff_ via gdal_translate.
Single-image non-geospatial files are converted into pyramidal tiff files via pyvips.
Multi-image tiff files are converted into tiff files with multiple pyramidal tiff images and have a custom image description to store frame details.
Some files can be read via the various tile sources in large_image without conversion but are inefficient (for example, uncompressed data in nd2 files). Converting these files will result in more efficient data access.
Installation
============
To install via pip with custom-built wheels:
``pip install large-image-converter[sources] --find-links https://girder.github.io/large_image_wheels``
The ``[sources]`` extra requirement is optional. When specified, all of the default large-image tile sources are installed for additional metadata extraction and format support.
Requirements
------------
If the custom-built wheels do not cover your platform, or you want to use different versions of tools, you can install the prerequisites manually. For full functionality, the following packages and libraries are needed:
- GDAL 3.1.0 or greater, including the command-line tools and the python library
- libtiff, including the command-line tools
- libvips
Additionally, the various tile sources for large_image can be used to read input files to extract and preserve metadata and to read files that can't be read via libvips or GDAL. The requirements of those sources need to be installed.
Usage
=====
Command Line
------------
In the simplest use, an image can be converted via:
``large_image_converter <source path>``
An output image will be generated in the same directory as the source image.
The full list of options can be obtained via:
``large_image_converter --help``
From Python
-----------
The convert function contains all of the main functionality::
from large_image_converter import convert
convert(<source path>)
# See the options
print(convert.__doc__)
From Girder
-----------
The converter is installed by default when ``girder-large-image`` is installed. It relies on Girder Worker to actually run the conversion.
The conversion task can be reached via the user interface on the item details pages, via the ``createImageItem`` method on the ``ImageItem`` model, or via the ``POST`` ``item/{itemId}/tiles`` endpoint.
Limitations and Future Development
==================================
There are some limitations that may be improved with additional development.
- For some multi-image files, such as OME Tiff files that cannot be read by an existing large_image tile source, the specific channel, z-value, or time step is not converted to readily usable metadata.
- Whether the original file is stored in a lossy or lossless format is not always determined. If unknown, the output defaults to lossless, which may be needlessly large.
.. _geotiff: https://gdal.org/drivers/raster/cog.html
Raw data
{
"_id": null,
"home_page": null,
"name": "large-image-converter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Kitware Inc",
"author_email": "kitware@kitware.com",
"download_url": "https://files.pythonhosted.org/packages/9b/1e/42d430e0dcd0f85124afc5fc5760e1b7c099344f5186e3931a6a541b49dc/large-image-converter-1.29.1.tar.gz",
"platform": null,
"description": "*********************\nLarge Image Converter\n*********************\n\nConvert a variety of images into the most efficient format for Large Image.\n\nGeospatial files are converted into cloud-optimized geotiff_ via gdal_translate.\nSingle-image non-geospatial files are converted into pyramidal tiff files via pyvips.\nMulti-image tiff files are converted into tiff files with multiple pyramidal tiff images and have a custom image description to store frame details.\n\nSome files can be read via the various tile sources in large_image without conversion but are inefficient (for example, uncompressed data in nd2 files). Converting these files will result in more efficient data access.\n\nInstallation\n============\n\nTo install via pip with custom-built wheels:\n\n``pip install large-image-converter[sources] --find-links https://girder.github.io/large_image_wheels``\n\nThe ``[sources]`` extra requirement is optional. When specified, all of the default large-image tile sources are installed for additional metadata extraction and format support.\n\nRequirements\n------------\n\nIf the custom-built wheels do not cover your platform, or you want to use different versions of tools, you can install the prerequisites manually. For full functionality, the following packages and libraries are needed:\n\n- GDAL 3.1.0 or greater, including the command-line tools and the python library\n- libtiff, including the command-line tools\n- libvips\n\nAdditionally, the various tile sources for large_image can be used to read input files to extract and preserve metadata and to read files that can't be read via libvips or GDAL. The requirements of those sources need to be installed.\n\nUsage\n=====\n\nCommand Line\n------------\n\nIn the simplest use, an image can be converted via:\n\n``large_image_converter <source path>``\n\nAn output image will be generated in the same directory as the source image.\n\nThe full list of options can be obtained via:\n\n``large_image_converter --help``\n\nFrom Python\n-----------\n\nThe convert function contains all of the main functionality::\n\n from large_image_converter import convert\n\n convert(<source path>)\n\n # See the options\n print(convert.__doc__)\n\nFrom Girder\n-----------\n\nThe converter is installed by default when ``girder-large-image`` is installed. It relies on Girder Worker to actually run the conversion.\n\nThe conversion task can be reached via the user interface on the item details pages, via the ``createImageItem`` method on the ``ImageItem`` model, or via the ``POST`` ``item/{itemId}/tiles`` endpoint.\n\nLimitations and Future Development\n==================================\n\nThere are some limitations that may be improved with additional development.\n\n- For some multi-image files, such as OME Tiff files that cannot be read by an existing large_image tile source, the specific channel, z-value, or time step is not converted to readily usable metadata.\n\n- Whether the original file is stored in a lossy or lossless format is not always determined. If unknown, the output defaults to lossless, which may be needlessly large.\n\n.. _geotiff: https://gdal.org/drivers/raster/cog.html\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "Converter for Large Image.",
"version": "1.29.1",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b5eed509de18b0bbbd1942e31cf56fa3ccbfb37850c11cd1cce42c74307a14e8",
"md5": "f2a31ccca8753620ff82dc6543f3c065",
"sha256": "1d0ac2c5073835b5f8864b68deb331541e5668caf1a36042100d97377088b609"
},
"downloads": -1,
"filename": "large_image_converter-1.29.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f2a31ccca8753620ff82dc6543f3c065",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 24875,
"upload_time": "2024-06-26T18:42:26",
"upload_time_iso_8601": "2024-06-26T18:42:26.491751Z",
"url": "https://files.pythonhosted.org/packages/b5/ee/d509de18b0bbbd1942e31cf56fa3ccbfb37850c11cd1cce42c74307a14e8/large_image_converter-1.29.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9b1e42d430e0dcd0f85124afc5fc5760e1b7c099344f5186e3931a6a541b49dc",
"md5": "59e54666c28441ef6873763b74d8649a",
"sha256": "121aa8e12c7a3d91cf4fbb028ae707e358f610eab95e16cc531f5b4dca042915"
},
"downloads": -1,
"filename": "large-image-converter-1.29.1.tar.gz",
"has_sig": false,
"md5_digest": "59e54666c28441ef6873763b74d8649a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24983,
"upload_time": "2024-06-26T18:42:35",
"upload_time_iso_8601": "2024-06-26T18:42:35.526648Z",
"url": "https://files.pythonhosted.org/packages/9b/1e/42d430e0dcd0f85124afc5fc5760e1b7c099344f5186e3931a6a541b49dc/large-image-converter-1.29.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-26 18:42:35",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "large-image-converter"
}
JSON