This fork features BioFormatsImageReader which provides support for reading over 100 image formats and potentially converting them to DZI pyramids suitable for using with different viewers, including, but not limited to, OpenSeadragon based viewers.
While the reader should work with the all formats supported by Bio-Formats, the preferred, most tested and efficient image input format is tiled TIFF/BigTIFF with LZW or JPEG compression. Please consider converting your images to the mentioned format by using ImageMagick tool, the command example:
magick convert -verbose -define tiff:tile-geometry=256x256 input_image.xxx -compress jpeg -quality 95 output_image.tif
This will produce 256x256 tiled JPEG (lossy) compressed TIFF file.
magick convert -verbose -define tiff:tile-geometry=256x256 input_image.xxx -compress lzw output_image.tif
This will produce 256x256 tiled LZW (lossless) compressed TIFF file.
Alternatively you can try to use bftools
Tip: avoid multipage TIFF files.
The CLI allows to build a DZI pyramid from an image.
To start the CLI, one should use pyramidio-cli-[version].jar like this:
java -jar pyramidio-cli-[version].jar -i my-image.jpg -o (my-output-folder || scheme:///path/file[.tar, .seq])
Examples:
java -jar pyramidio-cli-[version].jar -i my-image.jpg -o outputfolder
java -jar pyramidio-cli-[version].jar -i my-image.jpg -o file:///tmp/outputfolder.tar
java -jar pyramidio-cli-[version].jar -i my-image.jpg -o s3://my-image-bucket/outputfolder
java -jar pyramidio-cli-[version].jar -i my-image.jpg -o hdfs://localhost:9000/outputfolder
java -jar pyramidio-cli-[version].jar -i my-image.jpg -o hdfs://localhost:9000/outputfolder.tar
java -jar pyramidio-cli-[version].jar -i my-image.jpg -o hdfs://localhost:9000/outputfolder.seq
To get the list of all the options, one can type:
java -jar pyramidio-cli-[version].jar -h
Please note that the default pyramid tiles format is the same as the input image. In case of TIFF you want to avoid this. The following command will specify the tiles format:
java -jar pyramidio-cli-[version].jar -i my-image.tif -tf png -o outputfolder
This will produce a pyramid with PNG (lossless) tiles.
java -jar pyramidio-cli-[version].jar -i my-image.tif -tf jpg -o outputfolder
This will produce a pyramid with JPG (lossy) tiles.
Caching the entire input image into the memory provides the best performance.
However, in case of large images it might cause memory overflow issues.
There are two types of them: java.lang.OutOfMemoryError: Java heap space and java.lang.RuntimeException: Cannot cache region java.awt.Rectangle.
By default the tool will try to guess a "safe" cache size and the corresponding value for it based on the input image dimensions and the memory heap size.
If that fails for some reason or you aren't satisfied with the performance try to manually set the -icr parameter:
java -jar pyramidio-cli-[version].jar -i my-image.tif -icr 0.1 -tf png -o outputfolder
This means that only 10% of an image will be read/cached.
The -icr values are in range [0, 1]:
0 - the cache is disabled. The smallest memory footprint. The safest. The slowest.
1 - the entire input image is kept in the cache. The fastest. Prone to memory overflow.
You can also try to increase the heap size by using standard Java -XmX parameter. While this might increase the performance, it will NOT help in case of java.lang.RuntimeException: Cannot cache region java.awt.Rectangle - this is internal Bio-Formats limitation: only 2GB of data can be extracted at one time.
If the input image is not RGB888 there is a chance that the output might be corrupted. To resolve this try to use -rgb parameter. This will force on the fly convertion to RGB888 and the resulting pyramid should be fine.
Example:
java -jar pyramidio-cli-[version].jar -rgb -i my-image.jpg -o outputfolder
The simplest way is to use OpenSeadragon JavaScript library. The example index.html file and the pyramid (tiled256_jpg.dzi file and tiled256_jpg_files folder) are here: https://github.com/darwinjob/pyramidio-bioformats/tree/master/test-data
The demo is avalable here https://darwinjob.github.io/pyramidio-bioformats/demo.html
To write a DZI pyramid, one should use the gov.nist.isg.pyramidio.ScalablePyramidBuilder class:
ScalablePyramidBuilder spb = new ScalablePyramidBuilder(tileSize, tileOverlap, tileFormat, "dzi");
FilesArchiver archiver = new DirectoryArchiver(outputFolder);
BioFormatsImageReader pir = new BioFormatsImageReader(imageFile);
spb.buildPyramid(pir, "pyramidName", archiver, parallelism);Currently the available FilesArchivers are:
DirectoryArchiver: save files in a directory on the filesystem.TarArchiver: save files in a tar file on the filesystem.SequenceFileArchiver: save files in a Hadoop sequence file.HdfsArchiver: save files on a HDFS filesystem.TarOnHdfsArchiver: save files in a tar file created on a HDFS filesystem.S3Archiver: save files to a folder on a S3 bucket.
As for the PartialImageReaders:
BioFormatsImageReader: read an image using Bio-Formats library.BufferedImageReader: read an image from the disk and store it in RAM.DeepZoomImageReader: read a DZI pyramid.MistStitchedImageReader: read a MIST translation vector.
To read a DZI pyramid, one should use the DeepZoomImageReader class:
File dziFile = new File("my-image.dzi");
DeepZoomImageReader reader = new DeepZoomImageReader(dziFile);
BufferedImage wholeImageZoom0_01 = reader.getWholeImage(0.01);
BufferedImage regionAtZoom0_1 = reader.getSubImage(
new Rectangle(x, y, width, height), 0.1);Similarly, one could use DeepZoomImageReaderUrl class:
URL dziUrl = new URL("http://my-image.dzi");
DeepZoomImageReaderUrl reader = new DeepZoomImageReaderUrl(dziUrl);
BufferedImage wholeImageZoom0_01 = reader.getWholeImage(0.01);
BufferedImage regionAtZoom0_1 = reader.getSubImage(
new Rectangle(x, y, width, height), 0.1);This software is based on https://github.com/usnistgov/pyramidio from the National Institute of Standards and Technology and https://www.openmicroscopy.org/bio-formats/ from The Open Microscopy Environment. First publication https://www.openmicroscopy.org/community/viewtopic.php?p=17715