# Export Automation Reference

Export scripts are defined in a standard XML file located under this folder\
`C:\ProgramData\VIOSO [version]\SPExtCalibCommOpDef.ini`

You can use arbitrary scripts from the export dialog: \
`File > Export Mapping` then check the box `"use settings from file"`

Below you can find the dictionary of the scripting language and file examples:

## Dictionary <a href="#bkmrk-dictionary" id="bkmrk-dictionary"></a>

Tag and attribute names and values are case-sensitive! You may specify a file version (currently it's 1.0), we do not expect any changes in future.

### CalibCommerceTask <a href="#bkmrk-calibcommercetask" id="bkmrk-calibcommercetask"></a>

There is one root object:

<table data-full-width="false"><thead><tr><th>attribute</th><th>parameters</th><th>description</th><th>version</th></tr></thead><tbody><tr><td><strong>Typ</strong></td><td> </td><td>the type of task, set to <code>export</code></td><td>5.0</td></tr><tr><td><code>Format</code></td><td><code>vwf</code></td><td>standard format, one file contains all data</td><td>5.0</td></tr><tr><td></td><td><code>vwf separated</code></td><td>separate file for every display, mapping file and blend-bitmap for each projector</td><td>5.0</td></tr><tr><td></td><td><code>x-file</code></td><td>DirectX compatible mesh file. Uses a viewport of -8,8 horizontally. Vertically multiply by screen aspect. Example a 16:10 screen gets -5,5 vertical viewport.</td><td>5.0</td></tr><tr><td></td><td><code>openwarp</code></td><td>Text file containing u-v coordinates; import to OpenWarp calibrator</td><td>5.0</td></tr><tr><td></td><td><code>mips</code></td><td>xml and blend bitmap, use only for testing; use TransferTask instead</td><td>5.0</td></tr><tr><td></td><td><code>MPCDI</code></td><td>exports a VESA MPCDI v2 conform warp file</td><td>5.0</td></tr><tr><td></td><td><code>SGC</code></td><td>exports to Sciss’ Uniview warp mesh</td><td>5.0</td></tr></tbody></table>

Grid based exports (x-file, openwarp, mips and MPCDI) use `SpecialParam`:

<table data-full-width="false"><thead><tr><th>SpecialParam</th><th>description</th><th>version</th></tr></thead><tbody><tr><td><code>qGridDimX</code></td><td>horizontal grid dimension</td><td>5.0</td></tr><tr><td><code>qGridDimY</code></td><td>vertical grid dimension</td><td>5.0</td></tr></tbody></table>

In case `CommonParam:bVirtualContentRect` is used:

<table data-full-width="false"><thead><tr><th>SpecialParam</th><th>description</th><th>version</th></tr></thead><tbody><tr><td><code>vParam0_X</code></td><td>width of virtual content</td><td>5.0</td></tr><tr><td><code>vParam0_Y</code></td><td>height of virtual content</td><td>5.0</td></tr></tbody></table>

### **Sub tags**

* CommonParam
* SpecialParam
* Task
* TransferTask

### CommonParam <a href="#bkmrk-commonparam" id="bkmrk-commonparam"></a>

Sets options in context of export and conversion operations. These are Boolean Attributes, set to nonzero to switch on and 0 to switch off. If an attribute is omitted, default is used.

<table data-full-width="false"><thead><tr><th>Attribute</th><th>default value</th><th>description</th><th>version</th></tr></thead><tbody><tr><td><code>bSilent</code></td><td>1</td><td> needs to be 1, as we are operating without GUI</td><td>5.0</td></tr><tr><td><code>bNoVC</code></td><td>0</td><td>do not apply warping grid, this is like having a full-screened VC</td><td>5.0</td></tr><tr><td><code>bNoGeomCorr</code></td><td>0</td><td>no geometric correction is applied</td><td>5.0</td></tr><tr><td><code>bNoMask</code></td><td>0</td><td>no masks are applied</td><td>5.0</td></tr><tr><td><code>bSeparatedSplitDisp</code></td><td>0</td><td>keep splits as separate mapping; if not set, spitted displays get stitched to a mapping in desktop monitor size</td><td>5.0</td></tr><tr><td><code>bAllToMaster</code></td><td>1</td><td>if set and a Super Compound is exported, all mappings from participating clients are copied to the master and processed there</td><td>5.0</td></tr><tr><td><code>bBlankUnusedSplitDispParts</code></td><td>0</td><td>if set: splitted parts are masked to black; if unset: parts are filled uniformly to appear unwarped not used if <code>bSeparatedSplitDisp</code> is set</td><td>5.0</td></tr><tr><td><code>bExactFileName</code></td><td>0</td><td>if set, the export file name does not get decorated by the current Display Compound name Note: if set and there are more than one Display Compound exported, the latter will overwrite the former files!</td><td>5.0</td></tr><tr><td><code>bUse3D</code></td><td>0</td><td>exports 3D mapping instead of a distortion map Note: this is only intended for dynamic eye warping and an already converted mapping (fisheye to pano/cylinder, flat screen or custom content space) is required</td><td>5.0</td></tr><tr><td><code>bVirtualContentRect</code></td><td>0</td><td>scales mapping coordinates to a virtual content rect, based on the scan. It calculates an optimal content size and based on this rects, to fill one channel. An extra .def file is written, containing the total virtual content size and all display channel’s rects. To preset content size use SpecialParam:vParam0_X and _Y. To preset region offset or size, you must use a TransferTask. Use attibutes vCntOffsetX and Y and vCntSizeX and Y.</td><td>5.0</td></tr><tr><td><code>bNiceFrustum</code></td><td>0</td><td>does a nice AutoFrustum, it widenes FoV by 1° and rounds up to next full degree</td><td>5.0</td></tr><tr><td><code>bSymmetricFrustum</code></td><td>0</td><td>causes the AutoFrustum to be symmetric, that means upper and lower as well as right and left FoV are the same angle. This is useful, if the IG does not support asymmetric frustum and just provides FoVX and FoVY.</td><td>5.0</td></tr><tr><td><code>blendFormat</code></td><td>0</td><td><p>applies to MPCDI and PULSE export. Set to number:</p><ul><li><code>0</code> - RGB8</li><li><code>1</code> - RGB16</li><li><code>2</code> - Grey8</li><li><code>3</code> - Grey16</li></ul><p>Use Grey formats for UnrealEngine nDisplay</p></td><td>5.1</td></tr><tr><td><code>FileName</code></td><td> </td><td>needs to be set if <code>bExactFileName</code> is used. Specify the export file name in export folder or path</td><td> </td></tr><tr><td><code>bMergeRemote</code></td><td>0</td><td>all clients (remote and local) will be merged to one export file</td><td>6.0</td></tr><tr><td><code>bMPCDIForward</code></td><td>0</td><td>MPCDI export will use forward manner (the destination position for each content pixel) instead of reverse (source content position for each display pixel)</td><td>6.0</td></tr><tr><td><code>bMPCDITopDown</code></td><td>0</td><td>flips the mapping along vertical axis. v'=1-v</td><td>6.0</td></tr><tr><td><code>bMPCDIRotate</code></td><td>0</td><td>prerotate mapping to display rotation</td><td>6.0.2</td></tr><tr><td><code>bUseDisplaySize</code></td><td>0</td><td>uses display size as region size. This will lower the effective resolution of the content, as it gets scaled down to make the biggest region fit, thus smaller regions get unused data. If not set, each region gets its individual optimal size depending on the set or calculated content size.</td><td>6.0</td></tr><tr><td><code>bNoBlacklevel</code></td><td>0</td><td>no blacklevel uplift correction is applied, the texture is not written to the export file. Use this for compatibility with old vwf and VIOSOWarpBlend implementations.</td><td>5.3</td></tr></tbody></table>

### SpecialParam <a href="#bkmrk-specialparam" id="bkmrk-specialparam"></a>

Set input parameter in context of an export or a conversion operation.

<table data-full-width="false"><thead><tr><th>Attribute</th><th>default value</th><th width="329">description</th><th>version</th></tr></thead><tbody><tr><td><code>vParam0_X</code> <code>vParam0_Y</code> <code>vParam0_Z</code> <code>vParam0_W</code></td><td>0</td><td>IEEE float 4-Vector</td><td>5.0</td></tr><tr><td><code>vParam1_X</code> <code>vParam1_Y</code> <code>vParam1_Z</code> <code>vParam1_W</code></td><td>0</td><td>IEEE float 4-Vector</td><td>5.0</td></tr><tr><td><code>vEyePoint_X</code> <code>vEyePoint_Y</code> <code>vEyePoint_Z</code></td><td>0</td><td>an eye point (IEEE float) in 3D</td><td>5.0</td></tr><tr><td><code>customCntSpaceName</code></td><td> </td><td>name of a frustum or model definition defining a view port or texture space</td><td>5.0</td></tr><tr><td><code>baseCntSpaceName</code></td><td> </td><td>name of a frustum defining a straight ahead view</td><td>5.0</td></tr><tr><td><code>templateFileName</code></td><td> </td><td>filename of a template to export a frustum with</td><td>5.0</td></tr><tr><td><code>qGridDimX</code></td><td>0</td><td>export grid dimension, horizontally</td><td>5.0</td></tr><tr><td><code>qGridDimY</code></td><td>0</td><td>export grid dimension, vertically</td><td>5.0</td></tr><tr><td><code>fGammaCorr</code></td><td>0</td><td>exponent each blend value is raised to. Defaults to 0 which does no change and is internally changed to 1. Required if the graphic pipeline of the client application has set gamma adjustment. Set to a value greater than 1, if blend regions are too bright or to a value less than 1, if blend regions appear too dark. If you know the set gamma value use same for correction.</td><td>5.0</td></tr></tbody></table>

### Task <a href="#bkmrk-task" id="bkmrk-task"></a>

Describes a computing operation on the current data

<table data-full-width="false"><thead><tr><th>Attribute</th><th>value</th><th>description</th><th>version</th></tr></thead><tbody><tr><td><code>Typ</code></td><td><code>convert</code></td><td>type of the task, converts a mapping</td><td>5.0</td></tr><tr><td><code>Format</code></td><td><code>custom content space conversion</code></td><td><p>converts to a model’s texture coordinate space, creates 3D mapping</p><ul><li>use <code>SpecialParam:customCntSpaceName</code> to specify a model</li></ul></td><td>5.0</td></tr><tr><td><br></td><td><code>observer conversion</code></td><td><p>converts a 3D mapping to a frustum</p><ul><li>use <code>SpecialParam:customCntSpaceName</code> to specify the frustum</li><li>set <code>SpecialParam:customCntSpaceName</code> to <code>*</code> to use the display names like created on AutoFrustum. This enables to convert multiple displays or compounds at once using appropriate frustums</li><li><p>set offset and scale for the source content</p><ul><li><code>vParam0_X</code> to specify horizontal scale, this is 1</li><li><code>vParam0_Y</code> to specify horizontal offset, this is 0</li><li><code>vParam0_Z</code> to specify vertical scale, this is 1</li><li><code>vParam0_W</code> to specify vertical offset, this is 0</li></ul></li></ul><p>Other values for scale and offset are only used, if there is a splitted windows display used as a single export. Then x=1/number of horiziontal displays, z=1/number of vertical displays, y=hIndex*1/number of horizontal displays.</p><ul><li><p>Example for a 2x2 split (i.e. Mosaic/Eyefinity, Datapath x4, etc):</p><ul><li>left-top: (hIndex=0,vIndex=0): x=0.5, y=0, z=0.5, w=0</li><li>left-bottom (hIndex=0,vIndex=1): x=0.5, y=0, z=0.5, w=0.5</li><li>right-top: (hIndex=1,vIndex=0): x=0.5, y=0.5, z=0.5, w=0</li><li>right-bottom: (hIndex=1,vIndex=1): x=0.5, y=0.5, z=0.5,w=0.5</li></ul></li><li><p>Example of a 3x1 split (i.e. Mosaic/Eyefinit, Matrox triple-head-2go, etc.):</p><ul><li>left: (hIndex=0): x=0.3333333, y=0, z=1, w=0</li><li>center: (hIndex=0): x=0.3333333, y=0.333333333, z=1, w=0</li><li>right: (hIndex=0): x=0.3333333, y=0.666666666, z=1, w=0</li></ul></li></ul></td><td>5.0</td></tr><tr><td><br></td><td><code>pseudo 3D plane</code></td><td><p>creates a 3D mapping from a normal camera scan</p><ul><li><p></p><ul><li><p>uses <code>SpecialParam</code>; "bend" = the distance between curve and chord</p><ul><li><code>vParam0_X</code> to specify width</li><li><code>vParam0_Y</code> to specify horizontal bend</li><li><code>vParam0_Z</code> to specify height</li><li><code>vParam0_W</code> to specify vertical bend</li></ul></li></ul></li></ul></td><td>5.0</td></tr><tr><td><br></td><td><code>pseudo 3D cylinder</code></td><td><p>creates a 360° panorama from a fisheye camera scan, creates 3D mapping</p><ul><li>use <code>SpecialParam:vParam1_X</code> to specify cylinder radius</li></ul></td><td>5.0</td></tr><tr><td><br></td><td><code>pseudo 3D sphere</code></td><td><p>creates 3D mapping of fisheye camera scan</p><ul><li><p>use <code>SpecialParam</code>:</p><ul><li><code>vParam1_X</code> to specify sphere radius</li><li><code>vParam0_Z</code> to specify v-mapping start angle defaults to 0, which is the Equator, thus makes a hemisphere. Giving a positive angle, up to 90°, makes the sphere more shallow, giving a negative angle, down to -90°, makes it more total sphere</li></ul></li></ul></td><td>5.0</td></tr><tr><td><br></td><td><code>pseudo 3D equirectangular</code></td><td><p>creates 3D mapping of fisheye camera scan</p><ul><li><p>use <code>SpecialParam</code>:</p><ul><li><code>vParam1_X</code> to specify sphere radius</li><li><code>vParam0_Z</code> to specify v-mapping start angle defaults to 0, which is the Equator, thus makes a hemisphere. Giving a positive angle, up to 90°, makes the sphere more shallow, giving a negative angle, down to -90°, makes it more total sphere</li><li>the image content space is transformed to sample from a panoramic image in equirectangular format</li></ul></li></ul></td><td>5.0</td></tr><tr><td><br></td><td><code>auto frustum</code></td><td><p>creates a frustum from 3D data of each display, named after the display</p><ul><li><p>uses <code>CommonParam</code>:</p><ul><li><code>bUse3D</code> enables automatic frustum export</li><li><code>Filename</code> specifies a filename the frustum will be exported to, if not set the filename set for exporting the mapping is used</li></ul></li><li><p>uses <code>SpecialParam</code>:</p><ul><li><code>vEyePoint</code> specifies an eye for that frustum</li><li><code>templateFileName</code> specifies a template to export</li><li><code>baseCntSpaceName</code> specifies the main view (straight ahead)</li></ul></li></ul></td><td>5.0</td></tr><tr><td><br></td><td><code>apply vc</code></td><td><p>the VC is applied to the 2D mapping. Use before a conversion to effect positions, use after to warp and mask</p><ul><li>uses <code>CommonParam:FimeName</code> to specify a VC file</li></ul></td><td>5.0</td></tr><tr><td><code>Device</code></td><td> </td><td>a device (display or camera) name. This task is only applied to mappings coming from a device with that name</td><td>5.0</td></tr><tr><td><code>Core</code></td><td> </td><td>a core IP address or (computer’s network) name. This task is only applied to mappings coming from a client with that IP or name</td><td>5.0</td></tr></tbody></table>

Sub tags, see Format attribute for exact usage:

* CommonParam
* SpecialParam

### TransferTask <a href="#bkmrk-transfertask" id="bkmrk-transfertask"></a>

Used to transfer a mapping or part of a mapping to a device or file. Note:

* Always use `Format=”vwf”` in CalibCommerceTask to gather all data
* You need the attribute `bUse3D`, if you do the conversion creating the 3D mapping in an export definition file

<table data-full-width="false"><thead><tr><th>Attribute</th><th>default value</th><th>description</th><th>since version</th></tr></thead><tbody><tr><td><code>Format</code></td><td> </td><td>export format, see CalibCommerceTask:Format</td><td>5.0</td></tr><tr><td><code>Device</code></td><td> </td><td>a device (display) name. This task is only applied to mappings referring to a device with that name.</td><td>5.0</td></tr><tr><td><code>Core</code></td><td> </td><td>a core IP address or (computer’s network) name. This task is only applied to mappings referring to a client with that IP or name</td><td>5.0</td></tr><tr><td><code>bUse3D</code></td><td>0</td><td>use 3D mapping, if just created by a conversion</td><td>5.0</td></tr><tr><td><code>vCntOffsetX</code></td><td>0</td><td>horizontal pixel offset of input content to virtual content. Make sure to specify virtual content size in &#x3C;task>&#x3C;SpecialParam></td><td>5.0</td></tr><tr><td><code>vCntOffsetY</code></td><td>0</td><td>vertical pixel offset of input content to virtual content. Make sure to specify virtual content size in &#x3C;task>&#x3C;SpecialParam></td><td>5.0</td></tr><tr><td><code>vCntSizeX</code></td><td>0</td><td>width of input content. Keep 0 to use projector width</td><td>5.4</td></tr><tr><td><code>vCntSizeY</code></td><td>0</td><td>height of input content. Keep 0 to use projector height</td><td>5.4</td></tr><tr><td><code>customCntSpaceName</code></td><td> </td><td>name of a frustum embedded in export file</td><td>5.0</td></tr><tr><td><code>baseCntSpaceName</code></td><td> </td><td>name of a frustum giving the straight ahead view for relative angles of the exported view</td><td>5.0</td></tr></tbody></table>

Sub tags:

* `Destination`: describes a device or file to write the mapping to
  * Attributes:
    * `Core`: a client/device IP address or computer name to send the data to. This is a PC running SPCalibrator/Anyblend or a warping device
    * `FileName`: a path, to write the mapping to, on the destination machine

## Examples <a href="#bkmrk-examples" id="bkmrk-examples"></a>

### **3D vwf Export with custom content space conversion**

```
<VIOSO>
<File version="1.0.0" /
<CalibCommerceTask Typ="export" Format="vwf" >
<CommonParam bUse3D="1" bSilent="0" bNoVC="0" bNoGeomCorr="0" bNoBlending="0" bNoMask="0" bSeparatedSplitDisp="1" bAllToMaster="1" bBlankUnusedSplitDispParts="0" bExactFileName="0"
FileName="vioso_local.vwf" />
<SpecialParam qGridDimX="21" qGridDimY="21" />
<Task Typ="convert" Format="custom content space conversion" >
<SpecialParam customCntSpaceName="Cylinder2x1" />
</Task>
<!-- transfer to clients -->
<TransferTask Format="vwf" Core="192.168.1.31" bUse3D="1" >
<Destination Core="192.168.1.31" FileName="C:\VIOSO\channel.vwf" />
</TransferTask>
<TransferTask Format="vwf" Core="192.168.1.32" bUse3D="1" >
<Destination Core="192.168.1.32" FileName="C:\VIOSO\channel2.vwf" />
</TransferTask>
<TransferTask Format="vwf" Core="192.168.1.33" bUse3D="1" >
<Destination Core="192.168.1.33" FileName="C:\VIOSO\channel3.vwf" />
</TransferTask>
</CalibCommerceTask>
</VIOSO>
```

### **2D vwf Export with a pseudo 3D sphere conversion**

```
<?xml version="1.0"?>
<VIOSO>
  <File version="1.0.0" />
  <CalibCommerceTask Typ="export" Format="vwf">
    <CommonParam bSilent="1" bNoVC="0" bNoGeomCorr="0" bNoBlending="0" bNoMask="0" bSeparatedSplitDisp="0" bAllToMaster="1" bBlankUnusedSplitDispParts="1" bExactFileName="1" bUse3D="0" />
    <Task Typ="convert" Format="pseudo 3D sphere" >
      <SpecialParam vParam1_X="1000.0"/>
    </Task>
    <TransferTask Format="vwf " Core="192.168.100.5" >
      <Destination Core="192.168.100.5" FileName="D:\Export\EXPORT_Client.vwf" />
    </TransferTask>
  </CalibCommerceTask>
</VIOSO>
```

### **MPCDI Export for Unreal Engine**

```
<?xml version="1.0"?> 
<VIOSO>
<CalibCommerceTask Typ="export" Format="MPCDI" >
<CommonParam blendFormat="3" bUse3D="1" bSilent="0" bSeparatedSplitDisp="1" bAllToMaster="1" bBlankUnusedSplitDispParts="0" bExactFileName="0"
FileName="D:\UE_ndisplay\f1_auto" />
<SpecialParam qGridDimX="2000" qGridDimY="2000" />
</CalibCommerceTask>
</VIOSO>
```