Update precompressed tile documentation

sphinx/formats/index.rst

@@ -31,4 +31,5 @@ available from our `sample image downloads site <http://downloads.openmicroscopy
     /supported-formats
     /metadata-summary
     pattern-file
+    precompressed
     options

sphinx/formats/precompressed.rst

@@ -0,0 +1,34 @@
+Support for "precompressed" tiles
+=================================
+
+Some formats allow reading and/or writing "precompressed" tiles.
+This feature is primarily intended for whole slide images, each of which may have thousands of tiles.
+Data representing these tiles may be compressed, either lossily or losslessly, depending on the
+file format, imaging modality, or acquisition configuration.
+
+When reading, this allows for retrieving compressed bytes that are as close as possible
+to what is actually stored in the file. Decompression (if necessary) is the responsibility
+of the consumer.
+
+When writing, compressed bytes instead of raw bytes can be provided to the writer,
+such that the writer will just save the provided compressed bytes instead of recompressing.
+
+See also :doc:`how to work with precompressed tiles in bfconvert </users/comlinetools/precompressed>`
+
+.. _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)

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 <precompressed>`
+
 .. option:: -extra-metadata METADATA FILE
 
     Enables the writing of additional supplemental metadata from an external file during the conversion process .

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 </formats/precompressed>`.
+
+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 <precompressed#readers>`)
+* the output format must have precompressed tile writing support (see :ref:`the list of supported writers <precompressed#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

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`