diff --git a/sphinx/formats/index.rst b/sphinx/formats/index.rst index 1d01a379..49ac5400 100644 --- a/sphinx/formats/index.rst +++ b/sphinx/formats/index.rst @@ -31,4 +31,5 @@ available from our `sample image downloads site ` + +.. _precompressed#readers: + +Formats that support precompressed tile reading +----------------------------------------------- + +* SVS (since 7.1.0) +* NDPI (since 8.0.0) +* DICOM (since 8.0.0) + +.. _precompressed#writers: + +Formats that support precompressed tile writing +----------------------------------------------- + +* DICOM (since 7.1.0) +* TIFF (since 8.0.0) +* OME-TIFF (since 8.0.0) diff --git a/sphinx/users/comlinetools/conversion.rst b/sphinx/users/comlinetools/conversion.rst index f3847d5b..66e9084c 100644 --- a/sphinx/users/comlinetools/conversion.rst +++ b/sphinx/users/comlinetools/conversion.rst @@ -301,10 +301,12 @@ correctly. So in Windows, the above example would read:: .. code-block:: - bfconvert -noflat -precompressed -compression JPEG CMU-1.svs CMU-1.dcm + bfconvert -noflat -precompressed CMU-1.svs CMU-1.dcm .. versionadded:: 7.1.0 + .. seealso:: :doc:`Summary of the precompressed tiles feature ` + .. option:: -extra-metadata METADATA FILE Enables the writing of additional supplemental metadata from an external file during the conversion process . diff --git a/sphinx/users/comlinetools/precompressed.rst b/sphinx/users/comlinetools/precompressed.rst new file mode 100644 index 00000000..2ff2c115 --- /dev/null +++ b/sphinx/users/comlinetools/precompressed.rst @@ -0,0 +1,31 @@ +"Precompressed" tiles +===================== + +See first :doc:`an overview of what precompressed tiles are and which formats support them `. + +This feature is primarily exposed in the :program:`bfconvert` command, using the `-precompressed` option. +When the `-precompressed` option is used, best results are obtained by: + +* using the `-noflat` option +* **not** using the `-compression` option (this can work, but may force tile recompression) +* **not** using the `-tilex` or `-tiley` options (this can work, but may force tile recompression) + +There are several advantages to converting using the "precompressed" feature for formats that support it: + +* faster tile read and write times, as no tile compression/decompression needs to be performed +* no change in compression quality +* very little change in file sizes between input and output data + +There are also a few disadvantages: + +* tile sizes cannot be changed during conversion +* compression type cannot be changed during conversion +* input and output format must support same compression type and tile size +* the input format must have precompressed tile reading support (see :ref:`the list of supported readers `) +* the output format must have precompressed tile writing support (see :ref:`the list of supported writers `) +* command-line tools other than :program:`bfconvert` do not currently make use of the precompressed tile API + +For additional discussion of the "precompressed" tiles feature, see: + +* https://forum.image.sc/t/vsi-to-dcm-file-conversion/98249/5 +* https://forum.image.sc/t/exporting-a-dicom-stack/99400 diff --git a/sphinx/users/index.rst b/sphinx/users/index.rst index 5e8e21fd..6eb5e2c5 100644 --- a/sphinx/users/index.rst +++ b/sphinx/users/index.rst @@ -44,6 +44,7 @@ for carrying out a variety of tasks: comlinetools/ijview comlinetools/xmlindent comlinetools/mkfake + comlinetools/precompressed .. seealso:: :doc:`/formats/options`