News • Examples • Documentation • Download • Buy • Forum • Contact

krpano Tools (Command-Line) Version 1.21

The krpanotools executable is the core tool for processing images (e.g. sphere/cube conversions, resizing and tiling) and for everything related to the license handling.
It can be called from command-line or from batch/script-files or from other applications.
The krpanotools application offers these functions:
  • makepano - make a template-based pano or tour.
  • maketiles - make or merge tile images. Can be also used for conversion and resizing.
  • convert - Convert or resize images.
  • makepreview - make a smooth panoramic preview image.
  • spheretocube - convert a spherical to a cubical pano image.
  • cubetosphere - convert a cubical to a spherical pano image.
  • protect - create viewer files with custom protection settings.
  • encrypt - encrypt files.
  • testserver - the krpano testing server.
  • register - license registration tool.

Makepano Tool

  • A tool for automatically making ready-to-use panos and tours.
  • Automatic image preparation for optimal viewing performance (sphere-to-cube conversion, tiled multi-resolution images, preview images).
  • Templates-based HTML and XML generation, fully customizable.
Syntax: 
krpanotools makepano [-config=###] [OPTIONS] inputfiles ...
Config:
  • Path to a config file.
  • By default the templates/vtour-multires.config file is used.
  • The config file is a simple text file with several settings for how to process the input images.
Options:
  • Set or overwrite any setting from the config file.
  • Can be used multiple times.
  • Syntax: -nameofthesetting=value.
Inputfiles:
  • One or more image filenames (supported image file formats).
  • Supported panoramic formats / image-projections:
    • Spherical / Equirectangular / 360x180 images
    • Cylindrical images (360x*)
    • Partial spherical or cylindrical images with any field-of-view.
    • Cubical images with six separated image files (one image per cube side).
    • Cubestrip images (the cube-face order and alignment will be auto-detected by image-content analyzing).
  • Supported stereoscopic panorama formats:
    • One 12x1 or 1x12 stereo-cubestrip image (=two 6x1 cubestrips side-by-side or two 1x6 cubestrips top-bottom).
    • One single image with two spherical 360x180 images with side-by-side or top-bottom arrangement.
    • Two 6x1 cubestrip images with a same 'basename' and some left/right tags for the side detection (e.g. _l and _r in the filename).
    • Two spherical 360x180 images with a same 'basename' and some left/right tags for the side detection (e.g. _l and _r in the filename).
  • Using wildcards like *.tif is possible and should be used when trying to pass more images at once.
  • Cubical images should have suffixes like _l, _f, _r, _b, _u, _d or names like left, front, right, back, up, down in their filenames to allow an automatic detection of the related cube-side.
  • Stereoscopic images with separated side-images should have the same 'basename' and pre- or suffixes that allow identifying the side (e.g. _l and _r or left, right or something similar.

Maketiles / Convert Tool

  • Split large images into smaller tiles.
  • Merge tiles together.
  • Convert image file formats.
  • Resize images (with 360 edge warping support).
  • Optimized for very low memory need, can process any size images.
Syntax: 
krpanotools maketiles inputfile outputfile [tilesize] [OPTIONS]
Inputfile: Outputfile: Tile Template Syntax:
  • A tile-template can contain several placeholders for addressing the actual tile:
  • %h - for the horizontal tile index.
  • %v - for the vertical tile index.
  • Optional one or more 0 characters between the % and the h or v can be used as number padding.
Tilesize:
  • The size of a tile.
  • For non-quad tiles use WIDTHxHEIGHT.
  • When the input image can't be divided exactly by the tilesize, then the right-column and bottom-row tiles will be smaller than the tile size.
  • Disable tiling by using 0 or by skipping that setting.
Options:
  • -indexbase=#
    • Set the tile start-index, default=1.
  • -jpegquality=#
    • Set the JPEG compression quality, 0 to 100, default=85.
  • -jpegsubsamp=#
    • Set the JPEG color subsampling, 444, 420, 420, 411, default=444.
  • -jpegoptimize
    • Optimize the JPEG Huffman compression tables.
    • Can reduce the files sizes a bit, for very large input images (Gigapixel and more) this can noticeable increase the memory need and slow down the processing.
  • -jpegprogressive
    • Use the progressive JPEG compression format.
  • -tiffcompress=#
    • Set the TIFF compression method, none, lzw, zip or jpeg, default=lzw.
  • -dpi=#
    • Write a custom DPI size to the image header.
  • -profile=#
    • Embedded Color Profile (ICC) settings:
    • COPY - copy the color profile from the input image to the output image.
    • CONVERT - convert to a sRGB color profile but don't embed the profile (default).
    • sRGB - convert to a sRGB color profile and embed a very small sRGB profile.
    • SKIP - skip / ignore an embedded color profile.
  • -noalpha
    • Remove the alpha channel (if there is one).
  • -8bit
    • Convert the output image to 8bit (for 16bit inputs).
  • -hmirror
    • Horizontally mirror the image.
  • -q
    • Quiet mode, no console output.
Options for tiled-input images:
  • -insize=#
    • The total size of the input image: WIDTHxHEIGHT.
  • -intilesize=#
    • The tile-size of the input image: SIZE or WIDTHxHEIGHT.
  • -inindexbase=#
    • Set the tile start-index of input image, default=1.
Options for resizing an image:
  • -resize=#x#
    • Resize the image to WIDTHxHEIGHT.
    • Use * for WIDTH or HEIGHT for a proportional resizing.
  • -scale=# or -scale=#x#
    • Scale the image by a given factor.
  • -keepaspect
    • Keep the original image aspect when resizing.
    • That means the image will be resized to fit into the given WIDTH or HEIGHT.
  • -hwrap
    • Wrap around horizontally when filtering (for 360x* panos).
  • -filter=#
    • Set which resize filter to use:
    • POINT
    • LINEAR
    • GAUSS
    • CUBIC
    • HAMMING
    • MITCHELL
    • LANCZOS (the default, best quality)

Examples for the Maketiles / Convert tool

1. Convert an image file format: 
krpanotools convert image.tif resized.jpg

2. Resize an image: 
krpanotools convert image.jpg small.jpg -resize=1000x500

3. Resize proportionally to a fixed width: 
krpanotools convert image.jpg small.jpg -resize=1000x*

4. Resize proportionally to be always within 1000x1000, e.g. results in sizes like 1000x700 or 600x1000 depending on the input size: 
krpanotools convert image.jpg small.jpg -resize=1000x1000 -keepaspect

5. Tile an image: 
krpanotools maketiles image.jpg tile_%v_%h.jpg 512

6. Merge tiles together (the total size need to be known): 
krpanotools maketiles tile_%v_%h.jpg image.jpg -insize=5000x5000 -intilesize=512

Makepreview Tool

  • Make a smoothed small preview panorama image.
  • For a faster loading experience.
  • The smoothing/blurring will be equally spherical distributed (an normal image blurring in an image-editor would cause artefacts at the nadir/zenith areas).
Syntax: 
krpanotools makepreview inputfiles [-o=outputfile] [OPTIONS]
Inputfiles:
  • Spherical or cubical pano images (supported image file formats).
  • Cubical images should have suffixes like _l, _f, _r, _b, _u, _d or names like left, front, right, back, up, down in their filenames to allow an automatic detection of the related cube-side.
  • Alternatively it would be possible specify the filesnames for the cubesides manually by using: -l=### -f=### -r=### -b=### -u=### -d=###.
Options:
  • -o=###
    • Set the name of the output image.
    • By default it will be *preview.jpg where * is the base input filename.
  • -cs
    • Make a cubestrip preview pano image.
    • For a better quality and a better browser support.
  • -gray
    • Make a grayscale preview image.
  • -size=#x#
    • Set the size of the preview image.
    • By default 1024x512 for spherical and 256x256 for cubical.
  • -smooth=#
    • Smooting / blurring factor, 0 to 100, default=77.
  • -jpegquality=#
    • Set the JPEG compression quality, 0 to 100, default=85.
  • -jpegsubsamp=#
    • Set the JPEG color subsampling, 444, 420, 420, 411, default=422.
  • -tiffcompress=#
    • Set the TIFF compression method, none, lzw, zip or jpeg, default=lzw.
  • -profile=#
    • Embedded Color Profile (ICC) settings:
    • COPY - copy the color profile from the input image to the output image.
    • CONVERT - convert to a sRGB color profile but don't embed the profile (default).
    • sRGB - convert to a sRGB color profile and embed a very small sRGB profile.
    • SKIP - skip / ignore an embedded color profile.
  • -q
    • Quiet mode, no console output.

SphereToCube Tool

  • Convert spherical or cylindrical pano images into a cubical format.
  • Can be also used to render a rectilinear view.
  • When the input image has an embedded color-profile, it will be copied to the output images.
Syntax: 
krpanotools spheretocube MODE inputfile outputfile [OPTIONS]
Mode:
  • CUBE - output 6 separate cube face images.
  • HCUBE - output a horizontal image strip.
  • VCUBE - output a vertical image strip.
  • CUBE32 - output a 3x2 arranged image strip.
  • CUBE23 - output a 2x3 arranged image strip.
  • VIEW - output a rectilinear view.
Inputfile:
  • A spherical or cylindrical input image (supported image file formats).
  • For a cylindrical image the -cylinder option need to be added.
  • For partial pano images the -infov=### option need to be added.
  • Special case - using a tiled-image as input:
    • Input syntax: tiled:tile_%v_%h.jpg:WIDTH:HEIGHT:TILESIZE
    • Ideal for low memory usage and faster processing on huge images. That means first tile the input image using the maketiles tool and then convert it to cube.
Outputfile:
  • The name of the cubical output image.
  • In CUBE mode cube-side suffixes will be added to the filenames.
Options for partial pano images:
  • -infov=HFOVxVFOV/VOFFSET
    • HFOV - the horizontal field-of-view in degrees.
    • VFOV - the vertical field-of-view in degrees (optional).
    • HFOV - a vertical offset in degrees (optional).
  • -cylinder
    • Define that the input image is cylindrical pano image.
Options for VIEW mode:
  • -fov=#
    • The vertical field-of-view in degrees for the rectilinear view image.
  • -lookat=H,V,R
    • Set the viewing rotation in krpano viewer form, by hlookat, vlookat, camroll.
  • -rotate=ORDER,X,Y,Z
    • Set a custom viewing rotation.
    • ORDER - the axis rotation order, can be XYZ, XZY, YXZ, YZX, ZXY, ZYX.
    • X,Y,Z - the rotation angles around the axis in degrees.
General options:
  • -outsize=#
    • Set a custom outputsize.
    • By default the size will be calculated depending on the size of the input image.
    • For the VIEW mode -outsize=WIDTHxHEIGHT need to be used.
  • -noautolevel
    • By default the input image will be automatic leveled when there are EXIF orientation information (e.g. from one-shoot panoramic cameras).
    • With this setting that leveling can be disabled.
  • -profile=#
    • Embedded Color Profile (ICC) settings:
    • COPY - copy the color profile from the input image to the output image (default).
    • CONVERT - convert to a sRGB color profile but don't embed the profile.
    • sRGB - convert to a sRGB color profile and embed a very small sRGB profile.
    • SKIP - skip / ignore an embedded color profile.
  • -fast
    • Faster but lower-quality processing.
  • -jpegquality=#
    • Set the JPEG compression quality, 0 to 100, default=85.
  • -jpegsubsamp=#
    • Set the JPEG color subsampling, 444, 420, 420, 411, default=444.
  • -jpegoptimize
    • Optimize the JPEG Huffman compression tables (recommended).
  • -jpegprogressive
    • Use the progressive JPEG compression format.
  • -tiffcompress=#
    • Set the TIFF compression method, none, lzw, zip or jpeg, default=lzw.
  • -cachesize=#
    • Size of the memory cache in MB, default=256.
  • -tempdir=###
    • Set a custom directory for temporary files.
  • -q
    • Quiet mode, no console output.

CubeToSphere Tool

  • Convert cubical pano images back to a spherical pano image.
  • When the input images have an embedded color-profile, it will be copied to the output image.
Syntax: 
krpanotools cubetosphere inputfiles -o=outputfile [OPTIONS]
Inputfiles:
  • The six images of a cubical pano (supported image file formats).
  • The images should have suffixes like _l, _f, _r, _b, _u, _d or names like left, front, right, back, up, down in their filenames to allow an automatic detection of the related cube-side.
  • Alternatively it would be possible specify the filesnames for the cubesides manually by using: -l=### -f=### -r=### -b=### -u=### -d=###.
Options:
  • -o=###
    • Set the name of the output image.
    • By default it will be *_sphere.tif where * is the base input filename.
  • -size=#x#
    • Size of the output image (WIDTHxHEIGHT)
    • By default: width = cubesize * PI, height = width / 2.
  • -fast
    • Faster but lower-quality processing.
  • -jpegquality=#
    • Set the JPEG compression quality, 0 to 100, default=85.
  • -jpegsubsamp=#
    • Set the JPEG color subsampling, 444, 420, 420, 411, default=444.
  • -jpegoptimize=#
    • Optimize the JPEG Huffman compression tables, true or false, default=true.
  • -tiffcompress=#
    • Set the TIFF compression method, none, lzw, zip or jpeg, default=lzw.
  • -tempdir=###
    • Set a custom directory for temporary files.
  • -q
    • Quiet mode, no console output.

Protect Tool

  • Generate a registered krpano viewer file with custom protection settings.
Syntax: 
krpanotools protect -o=outputfilename [OPTIONS]
Outputfilename:
  • Path/filename of an output krpano.js viewer file.
Options:
  • -domain=###
    • Limit the usage to the given domain.
    • Can be used multiple times.
  • -expire=YYYY-MM-DD
    • Set an expire date.
    • After that date the viewer will stop working and show an expired information.
  • -expiredurl=###
    • Open/redirect to the given url after the expire date.
  • -nolu
    • Local / offline usage will be not allowed.
  • -noep
    • No external parameters - it will be not possible to pass parameters/variables to the krpano viewer during the viewer embedding.
  • -nojs
    • No Javascript interface - it will be not possible to communicate with the krpano viewer by its Javascript API.
  • -noex
    • Disallow the loading of external xml and plugins from other domains.
  • -noee
    • Block the viewer embedding into external (cross-domain) iframes.
  • -pxml
    • Allow only the loading of private-encrypted xml files.
    • Unencrypted or public-encrypted files will be not loadable.
  • -pplg
    • Allow only the loading of private-encrypted plugin files.
    • Unencrypted or public-encrypted files will be not loadable.
  • -bf
  • -demo
    • Generate a unregistered demo-watermarked krpano viewer (even when a krpano license is registered).
  • -q
    • Quiet mode, no console output.

Encrypt Tool

  • Encrypt files.
  • Only the krpano viewer will be able to load such encrypted files.
  • As 'private' encryption key the krpano license will be used. That means only a krpano viewer registered with the same license will be able to load the encrypted files.
Syntax: 
krpanotools encrypt [OPTIONS] inputfiles
Inputfiles:
  • Any files (placeholder * allowed).
  • Supported file formats: xml, js, json, stl, depth, obj, mtl, txt.
  • By default a .encrypted postfix will be added to the filename.
Options:
  • -p
    • Use a 'public' encryption key.
    • Everyone will be able to load the encrypted files.
  • -ow
    • Overwrite the original input file.
  • -bk
    • Overwrite the original input file, but make a backup before.
  • -in=### and -out=###
    • Manually set the input and output filename.
    • When using stdout as output filename, the encrypted filedata will be written to the console.
  • -q
    • Quiet mode, no console output.

Registration Tool

  • Register krpano license codes or show or remove already registered licenses.
Syntax: 
krpanotools register [PARAMETER]
Parameter:
  • ###
    • Register the given krpano license code on the system.
  • show
    • Show the current registration information.
  • remove
    • Remove the registration information from the system.

Special License Usage

  • For some special usage cases there are additional parameters for using the krpano license.
  • This could be used e.g. on web-servers when storing the license is unwanted or doesn't work.
Syntax: 
krpanotools ... -license=### -needlicense
Parameters:
  • -license=###
    • Use the given krpano license code for the current call.
    • The license will be not registered on the system and be used only for the current call.
  • -needlicense
    • Force the requirement of a valid license (either normally registered or by the license parameter).
    • When there is no valid krpano license, the tool will stop with exit/return code 1.

Supported Image File Formats

The krpano tools are supporting these image file formats:
  • TIFF (.tif, .tiff)
    • Limitations: TIFF files are limited to a 2 gigabytes filesize.
  • BigTIFF (.btf, .tf8, .bigtiff)
    • Limitations: none.
  • JPEG (.jpg, .jpeg)
    • Limitations: The maximum image size is 65535×65535px.
  • PNG (.png)
    • Limitations: Only supported as input images at the moment.
  • Photoshop Document (.psd)
    • Limitations: The maximum image size is 30000x30000px.
  • Photoshop Big Document (.psb)
    • Limitations: The maximum image size is 300000x300000px.
  • Kolor RAW (.kro)
    • Limitations: none.
All formats are only supported in 8 or 16bit RGB or RGBA format.