Image Conversion
The large_image library can read a variety of images with the various tile source modules. Some image files that cannot be read directly can be converted into a format that can be read by the large_image library. Additionally, some images that can be read are very slow to handle because they are stored inefficiently, and converting them will make a equivalent file that is more efficient.
Python Usage
The large_image_converter module can be used as a Python package. See large_image_converter for details.
Command Line Usage
Installing the large-image-converter module adds a large_image_converter command to the local environment. Running large_image_converter --help displays the various options.
usage: large_image_converter [-h] [--version] [--verbose] [--silent]
[--overwrite] [--tile TILESIZE] [--no-subifds]
[--subifds] [--frame ONLYFRAME]
[--format {tiff,aperio}]
[--compression {,jpeg,deflate,zip,lzw,zstd,packbits,jbig,lzma,webp,jp2k,none}]
[--quality QUALITY] [--level LEVEL]
[--predictor {,none,horizontal,float,yes}]
[--psnr PSNR] [--cr CR]
[--shrink-mode {mean,median,mode,max,min,nearest,default}]
[--only-associated _KEEP_ASSOCIATED]
[--exclude-associated _EXCLUDE_ASSOCIATED]
[--concurrency _CONCURRENCY] [--stats]
[--stats-full]
source [dest]
Convert files for use with Large Image. Output files are written as tiled tiff
files. For geospatial files, these conform to the cloud-optimized geospatial
tiff format (COG). For non-geospatial, the output image will be either 8- or
16-bits per sample per channel. Some compression formats are always 8-bits per
sample (webp, jpeg), even if that format could support more and the original
image is higher bit depth.
positional arguments:
source Path to source image
dest Output path
options:
-h, --help show this help message and exit
--version Report version
--verbose, -v Increase verbosity
--silent, -s Decrease verbosity
--overwrite, -w, -y Overwrite an existing output file
--tile TILESIZE, --tile-size TILESIZE, --tilesize TILESIZE, --tileSize TILESIZE, -t TILESIZE
Tile size. Default is 256.
--no-subifds When writing multiframe files, do not use subifds.
--subifds When writing multiframe files, use subifds.
--frame ONLYFRAME When handling a multiframe file, only output a single
frame. This is the zero-based frame number.
--format {tiff,aperio}
Output format. The default is a standardized pyramidal
tiff or COG geotiff. Other formats may not be
available for all input options and will change some
defaults. Aperio (svs) defaults to no-subifds. If
there is no label image, a cropped nearly square
thumbnail is used in its place if the source image can
be read by any of the known tile sources.
--compression {,jpeg,deflate,zip,lzw,zstd,packbits,jbig,lzma,webp,jp2k,none}, -c {,jpeg,deflate,zip,lzw,zstd,packbits,jbig,lzma,webp,jp2k,none}
Internal compression. Default will use jpeg if the
source appears to be lossy or lzw if lossless. lzw is
the most compatible lossless mode. jpeg is the most
compatible lossy mode. jbig and lzma may not be
available. jp2k will first write the file with no
compression and then rewrite it with jp2k the
specified psnr or compression ratio.
--quality QUALITY, -q QUALITY
JPEG or webp compression quality. For webp, specify 0
for lossless. Default is 90.
--level LEVEL, -l LEVEL
General compression level. Used for deflate (zip)
(1-9), zstd (1-22), and some others.
--predictor {,none,horizontal,float,yes}, -p {,none,horizontal,float,yes}
Predictor for some compressions. Default is horizontal
for non-geospatial data and yes for geospatial.
--psnr PSNR JP2K peak signal to noise ratio. 0 for lossless.
--cr CR JP2K compression ratio. 1 for lossless.
--shrink-mode {mean,median,mode,max,min,nearest,default}, --shrink {mean,median,mode,max,min,nearest,default}, --reduce {mean,median,mode,max,min,nearest,default}
When producing lower resolution images, use this
method for computing pixels. This defaults to median
for lossy images and nearest for lossless images.
--only-associated _KEEP_ASSOCIATED
Only keep associated images with the specified keys.
The value is used as a matching regex.
--exclude-associated _EXCLUDE_ASSOCIATED
Exclude associated images with the specified keys. The
value is used as a matching regex. If a key is
specified for both exclusion and inclusion, it will be
excluded.
--concurrency _CONCURRENCY, -j _CONCURRENCY
Maximum processor concurrency. Some conversion tasks
can use multiple processors. A value <= 0 will use the
number of logical processors less that number. This is
a recommendation and is not strict. Default is 0.
--stats Add conversion stats (time and size) to the
ImageDescription of the output file. This involves
writing the file an extra time; the stats do not
include the extra write.
--stats-full, --full-stats
Add conversion stats, including noise metrics (PSNR,
etc.) to the output file. This takes more time and
temporary disk space.