krpano 1.19-pr16 (build 2018-04-04)

krpanotools Config File Reference

The krpanotools makepano tool (and the droplets derived from it like MAKE PANO, MAKE VTOUR) will be configured by external configuration (.config) files. When calling the krpanotools makepano tool, it is necessary to specify a path to such .config file. The config files itself are just simple text files and can be editing with any text editor.

Syntax

The syntax of the config files is pretty simple. The config files are read line-by-line. Each line can be either a setting or a comment or an include. Empty or whitespace lines will be ignored.
  • Settings
    To set a setting just write: 
    setting=value
    Each line start with the name of setting, then follows an assignment character (=) and the value for this setting.
  • Comments
    When a line begins with a # character, then this line is treated as comment and will be ignored. 
    # this line is a comment and will be ignored
  • Includes
    It's possible to include other config files. Just write include and the name of the file: 
    include name-of-the-other-file

Notes about file paths

When defining the paths for the output-files, it is possible to use placeholders to refer to the input-path and to the pano-name.

These placeholders are available:
  • %INPUTPATH%
    This is the full path of the current input-file. It can be used to generate the output-file in the same folder as the input-file.
  • %BASENAME%
    This is the 'basename' of a input-image. It is the file-name without file-path and without file-extension. Pre- or post-fixes that are indicating the cube-side were also removed.
    When the name of the input-file doesn't allow generating a basename, then the basename will be 'pano####', where #### is a sequential number which starts at 0000.

All Config Settings

Input Image Settings Stereo Settings Processing Settings Format Conversion Settings (Sphere/Cylinder to Cube) Multi-Resolution Image Settings Output Images / Tile-Paths Setings Preview Pano Setings Custom Cube Images Thumbnail Image Settings XML Output Settings XML Template / Skin Settings XML Image Settings HTML Output Settings HTML Template Settings Protection Settings Basic / Setup Settings Image Filtering / Compression Settings

Settings Documentation

Input Image Settings 
panotype=autodetect
  • The panoramic type of the input image.
  • Possible settings:
    • autodetect - The type will be detected by the imagesize / aspect:
      • 2:1 aspect = spherical pano
      • 1:1 aspect and six files with the same 'basename' = cubical pano
      • other aspects - ask the user
    • sphere - force assuming that the input is a full spherical 360x180 image
    • cylinder - force assuming that the input is a 360x* cylinder
    • flat - force assuming that the input is a flat image
    • partialsphere - force assuming a partial sphere (hfov setting needed)
    • partialcylinder - force assuming a partial cylinder (hfov setting needed)
hfov=360
vfov=auto
voffset=0
  • Predefined settings for partial spherical/cylinder panos.
  • hfov - Set the horizontal field of view of the input images.
  • vfov - Set the vertical field of view of the input images. Use 'auto' to let this value be calculated automatically.
  • voffset - Shift the image vertically up or down away from the horizon/center (+/- degrees).

Stereo Settings 
stereosupport=true
  • When enabled (true) stereo (left/right) images will be generated when there is a stereoscopic input image.
  • When disabled (false), the pano will be build only for the left image of the stereoscopic input image.
  • This could be used to build large monoscopic images for normal viewing and special smaller-sized images via the customimage settings for VR stereo viewing. 
stereolabels=1|2
  • The labels for the left and right images when generating stereoscopic output images.

Processing Settings 
makescenes=false
  • Generate a single xml file with a <scene> elements for each input image. A <scene> is like an 'inline-xml'. This can be used for automatically generating virtual tours.
  • When disabled, a xml file for each input image will be generated.
frames=false
  • Enable 'multi-frame' / 'object' panos.
  • Each input image is treated as single frame of a movie or animation.
  • All input images need to have the same image size for this case.
  • The tilepath need to use the '%f' placeholder for the current frame number.

Format Conversion Settings (Sphere/Cylinder to Cube) 
converttocube=true
  • Convert spherical and cylindrical images automatically to cubical images.
  • Cubical images give a better display quality and a better rendering performance.
  • Cubical images are necessary for HTML5 usage.
converttocubelimit=360x120
  • Set the pano 'field-of-view-range' when a pano image should to be converted to cubical. When the pano range is above this limit it will be convereted, when below then not.
  • At the moment only 360x* images can be converted.
converttocubeformat=kro
  • Image fileformat for the temporary converted cube images.
  • Possible settings:
    • kro = Kolor RAW (no limits, default, recommended)
    • tif, tiff = TIFF (max. filesize 4GB)
    • btf, tf8, bigtiff = BigTIFF (no limits)
    • psd = Photoshop Document (max. imagesize 30.000x30.000)
    • psb = Photoshop Big Document (max. imagesize 300.000x300.000)
    • jpg, jpeg = JPEG (max. imagesize 30.000x30.000)
tempcubepath=%INPUTPATH%/%BASENAME%_cube%UID%
  • The path and name of the temporary to-cube-converted images (without file-extension).
  • The temporary cube images will be removed automatically after processing.
  • See the notes about file paths for details about the file path placeholders.
  • Additional here a %UID% placeholder is supported for generating an unique id. This should be used to avoid problems when files with the same name were located in the folder. 
waitafterconvert=false
  • Wait for an user keypress after converting to cube image.
  • This allows editing the cube image before final processing.

Multi-Resolution Image Settings 
multires=true
  • Should the tool generate multi-resolution images or 'normal' non-tiled single images.
tilesize=auto
  • Size of the multi-resolution tile images.
  • Should be between 256 and 1024.
  • Use 'auto' to let the tool automatically find a good value for 'symmetric tile splitting', which can improve the Flash rendering performance.
  • A today recommendation with a view to future versions with GPU rendering and HTML5 would be using 512 as tilesize.
  • Note - the tilesize affects the loading and decoding time and also the rendering performance.
levels=auto
  • Number of multi-resolution levels to generate.
  • Use 'auto' to let the tool automatically calculate the needed levels.
  • The number of the automatic levels depends on the image size of the panorama and the on the minsize and maxsize settings. 
levelstep=2
  • Each multi-resolution level will be reduced by the 'levelstep' factor from the last resolution level.
  • Example - levelstep and the level size:
    levelstep=2.0: 10000x5000, 5000x2500, 2500x1250
    levelstep=2.5: 10000x5000, 4000x2000, 1600x850
levelsizes=...
  • Set manual level sizes by a comma-separated list.
  • Only the width size will be set, the height will be calculated proportionally.
  • The levels and levelstep setting will be ignored when this setting will be set.
  • Example:
    levelsizes=512, 1024, 2048, 4096, 8192
adjustlevelsizes=true
  • Automatically adjust some level sizes to make them better divisible by the tilesize.
  • This will avoid very narrow tile images and can improve the loading and rendering performance.
adjustlevelsizesformipmapping=true
  • Automatically adjust / optimize the level sizes to make them better suitable for rendering with enabled mipmapping.
  • This can improve the loading and rendering performance.
  • This setting will be only applied when also the adjustlevelsizes setting is enabled.
minsize=auto
  • The minimum size (height) for multi-resolution levels.
  • When levels=auto then levels will be generated down to this size.
  • Use 'auto' to let the tool automatically choose the minimum size.
maxsize=auto
  • The maximum size (height) for multi-resolution levels.
  • When the input image is larger than this size, then it will be downsampled to this size.
  • Use 'auto' to use the maximum size of the input image.
maxcubesize=auto
  • The maximum size (width/height) for the cube images.
  • Use 'auto' to use the maximum size of the input image.

Output Images / Tile-Paths Setings 
tilepath=%INPUTPATH%/%BASENAME%.tiles/l%Al[_c]_%Av_%Ah.jpg
  • The path and name template for the output tile images.
  • See the notes about file paths for details about the file path placeholders.
  • The tilepath has several placeholders for tile-indices:
    • %l - index/number of the current multi-resolution level
    • %h - horizontal tile index (also possible: %x, %c, %u)
    • %v - vertical tile index (also possible: %y, %r)
    • [c] - The 'c' will be replaced by the cubeside character, everything else between [ and ] will kept as it is for cubical panos and be removed for other pano types.
    • %f - frame index (for multi-frame input)
  • Formating options:
    • Insert one or more '0' characters or an 'A' between the '%' and the placeholder characters to to 'fill up' the numbers with '0' characters for an uniform padding.
    • 'A' means 'automatic' - here as many '0' characters as needed will be added for an uniform padding for all tiles.
  • Each placeholder can be used several times and for the filename and also for the foldername. New folders will be created automatically.
  • Note - for very large panos organize the tiles into several folders to keep the 'number of files per folder' low - that's better for good server performance! 
tilepathxml=[PATH]
  • Template for the path in the xml.
  • Can be used to pre- or postfix the path.
indexbase=1
  • Numbering start/base index for the tile-indices.

Preview Pano Setings 
preview=true
  • Generate a small and smooth preview image.
  • The smoothness of the preview image makes it possible to compress the image very well and make the filesize very small. And this allows a very quick loading.
  • The preview image will be display behind the normal pano during loading.
cspreview=true
  • Generate a cubestrip preview images when possible.
  • Cubic images have a better, more accurate display quality.
  • In HTML5, cubestrip preview images are the only supported preview image format.
graypreview=false
  • Make the preview image grayscaled.
previewsmooth=25
  • Smoothness of the preview image.
  • 0-100 (higher values are smoother)
previewspsize=1024
  • Size (width) of spherical preview images.
  • Default is 1024 ⇒ 1024x512.
previewcssize=256
  • Size (width) of cubestrip (cspreview=true) preview images.
  • Default is 256 ⇒ 256x1536.
previewpath=%INPUTPATH%/%BASENAME%.tiles/preview.jpg
  • The path and name of the output preview image.
  • See the notes about file paths for details about the file path placeholders.
previewpathxml=[PATH]
  • Template for the path in the xml.
  • Can be used to pre- or postfix the path.

Custom Cube Images 
customimage[name].path=...
  • Generate smaller sized cube images.
  • The [name] is any internal unique name.
  • The path and filename of the custom cube images. The name need to contain the cube-side placeholder '%s'.
  • See the notes about file paths for details about the file path placeholders.
customimage[name].size=1024
  • Resolution / size of the custom cube images.
  • When the normal pano size is already smaller than this size, no custom image will be generated.
customimage[name].imagesettings=...
customimage[name].stereosupport=...
  • Generate stereo images when the input is a stereo image.
  • Possible settings: true or false or 'not set'. When 'not set' then the stereosupport setting will be used.
customimage[name].xml=...
  • XML Template for the custom cube images.
  • Possible placeholders:
    • [PATH] - path to the custom cube images
    • [TAB] - tabulator indentation
    • [NL] - new-line
customimage[name].xmllevel=...
  • Define where to insert the custom image xml.
  • Possible settings:
    • image - add the xml inside the <image> element.
    • root - add the xml at the root level (e.g. <krpano> or <scene>).
customimage[name].xmlsceneparameters=...
  • Parameters / attributes that will be added to the <scene> element when the custom image will be added.
customimage[name].xmlimageparameters=...
  • Parameters / attributes that will be added to the <image> element when the custom image will be added.
Custom Cube Image Example

An example for generating 1024x1024 cube images for mobile devices: 
customimage[mobile].path=%INPUTPATH%/%BASENAME%.tiles/mobile_%s.jpg
customimage[mobile].res=1024
customimage[mobile].imagesettings=jpegquality=82 jpegsubsamp=444 jpegoptimize=true
customimage[mobile].xml=<mobile>[NL][TAB]<cube url="[PATH]" />[NL]</mobile>


Thumbnail Image Settings 
makethumb=false
  • Automatically generate a small thumbnail image.
  • For cube-panos this thumbnail will be based on the front-cube-side-image, for all other panos the whole image itself will be used.
thumbsize=80
  • The square pixel-size of the thumbnail image.
thumbpath=%INPUTPATH%/%BASENAME%.tiles/thumb.jpg
  • The path and name of the thumbnail image.
  • See the notes about file paths for details about the file path placeholders.
thumbpathxml=[PATH]
  • Template for the path in the xml.
  • Can be used to pre- or postfix the path.

XML Output Settings 
xml=true
  • Generate a xml file.
  • The xmltemplate file will be used as template/base for generating the xml file.
xmlpath="%INPUTPATH%/%BASENAME%.xml
  • The path and name of the output xml file.
  • See the notes about file paths for details about the file path placeholders.

XML Template / Skin Settings 
xmltemplate=...
  • Template file the output xml file.
  • Possible placeholders:
    • [NAME] - (unfiltered) basename of the pano
    • [BASENAME] - (filtered) basename of the pano
    • [PREVIEW] - place for the <preview> element
    • [IMAGE] - place for the <image> element
    • [SCENES] - place for the <scene> elements
    • [VIEW] - place for the <view> element (based on xmltemplate_view)
    • [PARTIALPANO] - placeholder for ispartialpano="true" for partial panos
    • [VIEWLIMITS] - placeholder for the viewing limits for partial panos
    • [HOTSPOTS] - place for the <hotspot> elements (based on xmltemplate_hotspot)
    • [THUMB] - place for the thumbnail thumburl="..." attribute
    • [DEVICE] - placeholder for devices="flash" for non-html5-compatible panos
    • [HAVEGPS] - insert true or false depending if the input image contains GPS information or not
    • [GPS] - shortcut for  lat="[LAT]" lng="[LNG]" heading="[HEADING]"
    • [LAT] - the GPS latitude value
    • [LNG] - the GPS longitude value
    • [HEADING] - the GPS heading value
    • [...] - Any custom placeholders by the xmltemplate_var setting
xmltemplate_var=name:value
  • A custom placeholder for the xmltemplate xml file.
  • Placeholders with [name] will be replaced by the given value
  • This setting can be used more than once to add several custom placeholders.
xmltemplate_additional_file=...
  • Additional files of the xmltemplate xml.
  • This setting can be used more than once to add several files.
  • All given files will be copied directly to the output folder.
xmltemplate_scene=...
  • Template file for the [SCENES] placeholder.
  • It's possible to use the same placeholders as in the xmltemplate.
xmltemplate_view=...
  • Template file for the [VIEW] placeholders.
xmltemplate_hotspot=...
  • Template file for the [HOTSPOTS] placeholders.

XML Image Settings 
xmlimageparameters=
  • Set additional parameters in the xml <image ...> node.
  • Can be used to set a different multiresthreshold.

HTML Output Settings 
html=true
  • Generate a output html file where the pano viewer is embedded.
  • The htmltemplate file will be used as template/base for generating the html file.
htmlpath=%INPUTPATH%/%BASENAME%.html
  • The path and name of the output html file.
  • See the notes about file paths for details about the file path placeholders.

HTML Template Settings 
htmltemplate=...
  • Template file the output html file.
  • Possible placeholders:
    • [XML] - path to the generated xml file
    • [NAME] or [BASENAME] - 'basename' of the pano
    • [SWF] - path to the generated swf file
    • [JS] - path to the viewer embedding script (htmltemplate_js)
    • [HTML5] - either the value of the htmltemplate_html5 setting or never
    • [...] - Any custom placeholders by the htmltemplate_var setting
htmltemplate_js=...
  • Path to viewer embedding script.
  • Will be inserted in the [JS] placeholder in the htmltemplate html file.
htmltemplate_html5=...
  • The value for the [HTML5] placeholder in the htmltemplate html file.
  • When HTML5-Output is available (=available license and compatible image), then the given value will bet set, but when HTML5 is NOT available - then the value never will be set. 
htmltemplate_var=name:value
  • A custom placeholder for the htmltemplate html file.
  • Placeholders with [name] will be replaced by the given value
  • This setting can be used more than once to add several custom placeholders.
htmltemplate_additional_file=...
  • Additional files of the htmltemplate html page.
  • This setting can be used more than once to add several files.
  • All given files will be copied directly to the output folder.

Protection Settings 
kprotectclparameters=...
  • Additional parameters for the internal protect tool when creating the viewer files.
  • Avialable parameters are:
    • -domain=# ... add a domain-limitation
    • -noep ... disable external parameters
    • -nojs ... disable the javascript interface
    • -nolu ... disable local / offline usage
    • -noex ... disallow loading external xml / plugin files from other domains
    • -pxml ... allow only privately-encrypted xml files
    • -expire=YYYY-MM-DD ... set a expire date
    • -expiredurl=# ... url to open at expire date
    • -swfsize=# ... set standalone size of the swf (WIDTHxHEIGHT)
    • -fs ... start in fullscreen mode (Standalone Flashplayer only)
    • -nomb ... no menu bar (Standalone Flashplayer only)
    • -nobf ... no branding free output (ignore branding free license)

Basic / Setup Settings 
html5=true
  • HTML5 support - true or false.
flash=true
  • Flash support - true or false.
profile=convert
  • The embedding color profile handling - settings:
    • skip - Skip / ignore embedded color profiles.
    • copy - Copy the color profile from the input to the output image.
    • convert - Convert the image colors from the embedded color profile to the sRGB color profile, but don't embed the sRGB profile in the output image (the default).
    • sRGB - Convert the image colors from the embedded color profile to the sRGB color profile, AND embed the sRGB profile in the output image (for best compatibility and color profile support, but with slightly larger image files and slower image decoding). 
parsegps=true
  • Parse the input-images for EXIF GPS information.
  • This can be used for creating automatically geo-tagged panos.
  • The GPS location will be available in the xml-template via placeholders.
autolevel=remap
  • Parse the input-images for EXIF or XMP orientation / leveling information.
  • Could be used for automatically leveling Ricoh Theta images.
  • Possible settings:
    • remap = Remap (rotate) the images itself to level them.
    • prealign = Keep the images as they are, but add a prealign setting in the xml to level them.
    • off = Don't level the images.
prealignheading=true
  • When enabled the EXIF or GPS orientation information will be used to add a prealign setting the <image> xml element that rotates the image to the 'heading' direction. 
filterbasename=true
  • Filter-out white-space, non-ASCII and special characters from the BASENAME and replace them with underline (_) characters.
  • This will avoid path problems across different systems with different character encodings.
cubeshortsyntax=true
  • Use the shorter <cube url="pano_%s.jpg" /> syntax instead of defining separate xml tags for each cube-side (<left url="pano_l.jpg" /> to <down url="_pano_d.jpg" />).
ignorelayers=false
  • Ignore when a PSD/PSB file contains layers and allow using such files as input.
  • Warning: Such PSD/PSB files should be saved with 'maximize compatibility' in Photoshop to be able to be loaded correctly.
sortinput=true
  • Sort the input files alphabetically.
askforxmloverwrite=true
  • Ask before overwriting an existing xml file.
quiet=false
  • No console output, process silently.
  • Only errors will be shown.
waitkey=false
  • Wait for a keypress after processing.
tempdir=...
  • Set the path where temporary files (swapped-out-memory) should be stored.
  • When not set, the system default will be used.
  • Note - the temporary cube images (tempcubepath) will not be stored there.

Image Filtering / Compression Settings 
filter=LANCZOS
  • Set the down-sampling filter for generating lower resolution levels and images.
  • Possible settings:
    • POINT = simple point filtering (bad quality)
    • LINEAR = linear filtering (better, but still bad quality)
    • CUBIC = cubic filtering (soft, loss of details)
    • HAMMING = hamming filter (good, only a little loss of details)
    • GAUSS = gaussion filtering (good, only a little loss of details)
    • MITCHELL = mitchell filtering (good quality for up-sampling)
    • LANCZOS = windowed sinc filter (best quality, keeps the most details)
jpegquality=85
  • Set the JPEG compression quality.
  • Settings: 1-100
    • lower values - worse image quality and smaller files
    • higher values - better image quality and larger files
  • Note - using quality settings higher than 95 wouldn't be recommended for web usage! The minimal increased image quality wouldn't be worth the much increased file sizes and therefore way longer download times. 
jpegsubsamp=422
  • Use JPEG Chroma subsampling for reducing the filesize.
  • More information: Wikipedia - Chroma subsampling
  • Possible settings:
    • 444 = no chroma subsampling (best quality)
    • 422 = horizontal (1/2) chroma subsampling
    • 420 = horizontal (1/2) and vertical (1/2) chroma subsampling (the jpeg default)
    • 411 = horizontal (1/4) and vertical (1/2) chroma subsampling (best compression)
jpegoptimize=true
  • Optimize the JPEG Huffman-compression tables.
  • This makes the JPEG images smaller and should be enabled in the most cases.
  • When enabled more working memory (RAM) is needed, because each image must be kept in memory until it is finished. For very large input-images and 32-bit systems, this memory usage can be too much - there it should be disabled.
jpegprogressive=false
  • Use progressive JPEG encoding.
  • Progressive JPEG images can be smaller, but they are typically slower to decode.
manualjpegcompression=false
  • Instead of JPEG images, loss-less TIFF images will be created.
  • These TIFF images need to be converted manually to JPEG images. Here it would be possible to use custom tools and settings for the jpeg conversion.
  • In the XML itself the normal JPEG filenames will be used.