close panorama

Tools / Droplets

krpanotools Config File Reference Version 1.18
Select Version:

The krpanotools makepano tool (and the derived from it droplets like MAKE PANO, MAKE VTOUR, ...) will be configured by external configuration files (.config). 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 kind of 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

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).

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 and iPhone/iPad 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.
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.

Multi-Resolution XML Settings
progressiveloading=auto
  • Set the <image ... progressive="..."> setting in the xml.
  • Progressive loading affects the loading order - the lowest resolutions will be loaded first and then step by step - resolution by resolution (but only for the current view!) will be loaded, until the currently needed resolution for the current view was reached.
    Without progressive loading the currently needed resolution will be loaded at first.
  • Possible settings: true, false or auto.
    When set to auto - the progressive loading will be enabled only for flat panos or large partial panos and be disabled for full spherical or cubical panos.
xmlimageparameters=
  • Set additional parameters in the xml <image ...> node.
  • Can be used to set a different multiresthreshold.
leveldownload=auto
leveldecode=auto
  • Set the download and decode settings for each level in the xml.
  • When set to auto the automatic mode will be used and no setting will be written in the xml.

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 (for mobile usage)
customimage[name].path=...
  • Generate smaller sized cube images.
  • The [name] is any internal unique name.
  • The path and name of the custom cube images. The name should 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.
customimage[name].imagesettings=...
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
Custom Cube Image Example
An example for generating 1024x1024 cube images for iPhone / iPad / Android:
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.

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.

Embedded SWF File Settings
buildembeddedswf=false
  • Build a swf file with embedded license and embedded data (Flash only).
  • Can be used for creating single all-contained swf files.
buildembeddedswf_files=xml,skin,preview,tiles
  • Select which files to embed when buildembeddedswf is enabled.
  • Possible options:
    • xml = embed the base xml (based on 'xmltemplate')
    • skin = embed the 'xmltemplate_additional_file' files
    • preview = embed the preview image
    • tiles = embed the pano tiles
embedorderlookat=0/0
  • Sort the embedded tiles to start loading with the tiles at the given looking position.
  • Spherical coordinates in 360x180 degree - 0/0 = image center.
kprotectclparameters=...
  • Additional parameters for the internal kprotectcl tool when creating swf 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=auto
  • Use / Include the HTML5 (iPhone/iPad) Viewer.
  • Possible settings:
    • auto = only when the HTML5 (iPhone/iPad) license (krpanoiphone.license.js) is available or when running in DEMO mode (no licenses at all)
    • true = always include the HTML5 Viewer
    • false = never include the HTML5 Viewer
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.
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.
krpanoswf=krpano.swf
  • Path to the base krpano.swf file.
  • The path is relative to the config file.
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.