XML Scene (.scn) format

Overview

SCN files are the main Corona scene descriptors. They include other files with geometry/materials/configuration, define camera, geometry, render elements, and more. The document root element must be of type “scene”. All element and attribute names are case-insensitive.

Camera definition is only required node. Everything else is optional and will stay at defaults if not defined. The basic syntax is:

<scene>
    <camera class="[string]">...</camera>
    *<confFile>[filename]</confFile>
    *<mtlLib>[filename]</mtlLib>
    ?<sun>...</sun>
    ?<environment>[map]|[RGB]</environment>
    ?<globalMedium>[string]</globalMedium>    
    *<geometryGroup>...</geometryGroup>
    *<renderElement>...</renderElement>
    ?<renderSelected>...</renderSelected>    
</scene>

Camera definition

• If the camera is animated, all values must be animated, and have the same number of steps.

• Different camera parameters are available, based on the camera class:

<camera class="[string]">...</camera>

Perspective camera

• FOV is always horizontal FOV specified in degrees.

• There are 3 different ways to define the basic geometry of the camera:

First option is to use origin and target points together with the “roll” vector (a vector pointing upwards - usually 0 0 1 for Z-up or 0 1 0 for Y-up) that rotates the camera around the origin-target axis:

<camera class="perspective">
    <origin>[XYZ]|[animXYZ]</origin>
    <target>[XYZ]|[animXYZ]</target>
    <roll>[XYZ]|[animXYZ]</roll>
    <fov>[float]</fov>
</camera>

Second option is to input the camera transformation matrix directly. The matrix transforms from the world space to the camera space. The camera is centered arount point 0 0 0 in the camera space space, looking in the negative Z axis with Y axis being roll:
Note: this method does not work in current version (15.03.2018), but will be re-introduced.

<camera class="perspective">
    <transform>[TM]|[animTM]</transform>
    <fov>[float]</fov>
</camera>

Last option is to specify origin and target points together with xVect and yVect vectors. Those specify the translation in the camera plane in the image x and y direction. This allows creating tilt-shift camera effects:

<camera class="perspective">
    <origin>[XYZ]|[animXYZ]</origin>
    <target>[XYZ]|[animXYZ]</target>
    <xVect>[XYZ]|[animXYZ]</xVect>
    <yVect>[XYZ]|[animXYZ]</yVect>
    <fov>float</fov>
</camera>  

There are also other, optional parameters:

?<filmWidth>[float]</filmWidth>
?<focalDist>[float]</focalDist>
?<fstop>[float]</fstop>
?<bokehPolygonal>
    <blades>[int]</blades>
    <rotation>[float]</rotation>
</bokehPolygonal>

• Specifying fStop, focalDist, filmWidth, or bokehPolygonal enables the depth of field effect.

Corona 2+

Since Corona 2, it is also possible to specify:

?<focalLengthForDof>[float]</focalLengthForDof>
?<lens>
    <centerBias>[float]</centerBias>
    <vignetting>[float]</vignetting>
    <anamorphic>[float]</anamorphic>
</lens>
?<lensDistortion>
    <cubicAmount>[float]</cubicAmount>
</lensDistortion>

• The valid range of centerBias is [-5, 5], for vignetting it is [-3, 3] and for anamorphic (-1, 1).

Ortho camera

<camera class="ortho">
either:
    <origin>[XYZ]|[animXYZ]</origin>
    <target>[XYZ]|[animXYZ]</target>
    <roll>[XYZ]|[animXYZ]</roll>
 
or:
    <transform>[TM]|[animTM]</transform>
    <width>[float]</width>
</camera>

Spherical camera

<camera class="spherical">
    <origin>[XYZ]|[animXYZ]</origin>
    <target>[XYZ]|[animXYZ]</target>
    <roll>[XYZ]|[animXYZ]</roll>
</camera>

Cylindrical camera

<camera class="cylindrical">
    <origin>[XYZ]|[animXYZ]</origin>
    <target>[XYZ]|[animXYZ]</target>
    <roll>[XYZ]|[animXYZ]</roll>
    <height>[float]</height>
</camera>

Cube map camera

<camera class="cubemap">
    <origin>[XYZ]|[animXYZ]</origin>
    <target>[XYZ]|[animXYZ]</target>
    <roll>[XYZ]|[animXYZ]</roll>
</camera>

Additional optional parameters for all types

    ?<region>
        <startX>[float]</startX>
        <startY>[float]</startY>
        <endX>[float]</endX>
        <endY>[float]</endY>
        ?<originalAspectRatio>[float]</originalAspectRatio>
    </region>
    ?<minT>[float]</minT>
    ?<maxT>[float]</maxT>
</camera>

Stereo/Virtual Reality options

Spherical,cube map, and perspective camera can also optionally specify vr tag to enable the stereo rendering mode:

?<vr>
    <eyeSeparation>[float]</eyeSeparation>
    ?<frontOffset>[float]</frontOffset>
    ?<convergenceDistance>[float]</convergenceDistance>
</vr>

Geometry group

Defines a group of one or more geometric objects to be inserted in the scene. Usually single scene object in 3D studio maps to single geometry group. A group in inserted in the scene as an “instance”. Single group can be inserted in the scene multiple times when multiple instances are defined, with different transformation matrices and materials. This saves memory and makes it possible for example to create large forests.

<geometryGroup>
    +<object class="[string]">...</object>
    +<instance>
        +<material>[string]</material>
        +<transform name="[string]">[TM]|[animTM]</transform>
    </instance>
</geometryGroup>

• One or more materials can be present. Order matters - material ID “n” of an object is resolved using n-th material in each instance.

• One or more transform nodes can be present. Each represents single instance with given set of materials. Order does not matter. Optional name parameter, if present, is used for include/exclude stuff.

Sphere object

<geometryGroup>
    <object class="sphere">
        <materialId>[int]</materialId>
    </object>    
</goemetryGroup>

Inserts a single sphere with given material ID at point 0 0 0 with radius of 1. A transformation matrix of the whole geometry group is used to properly position the sphere.

File include objects

<geometryGroup>
    <object class="file">[filename]</object>    
</goemetryGroup>

Parses additional file (.obj or .cgeo) and inserts it into this geometry group

Global medium

Sets the scene global medium to a specified material. Only the volumetric properties of the material will be used to replace the default medium in the scene.

<globalMedium>
    [material]
</globalMedium>

Render selected

Activates the “render selected” mode. Only included/non-excluded objects will be rendered, rest of the scene will be black. The included/excluded strings are names of instances in geometryGroup → instance → transform

<renderSelected>[includeList]</renderSelected>

Sun

Activates the sun in the scene and sets its position (specified as dirTo, vector pointing towards the sun from the scene origin), and optionally other parameters. Parameter dirUp specifies the direction to zenith (by default vector (0,0,1)), available since Corona 2.

<sun>
    <dirTo>[XYZ]</dirTo>
    ?<dirUp>[XYZ]</dirUp>
    ?<colorMode>constantWhite|realistic|realisticTextured</colorMode>
    ?<colorMult>[RGB]</colorMult>
    ?<turbidity>[float]</turbidity>
    ?<sizeMult>[float]</sizeMult>
    ?<visibleDirect>[bool]</visibleDirect>
    ?<visibleReflect>[bool]</visibleReflect>
    ?<visibleRefract>[bool]</visibleRefract>
    ?<includeExclude>[includeList]</includeExclude>
</sun>

where sizeMult is between 0.1 to 64 and turbidity is between 1.7 to 10.

Environment

Sets scene environment to a constant color or a map.

<environment>[RGB]|[map]</environment>

Materials

Parses mtl library, saves material names so instances can reference them later:

<mtllib>[filename]</mtllib>

Configuration file

Immediately parses a configuration (.conf) file with given filename.

<conffile>[filename]</conffile>

Render Elements

Each renderElement node specifies a new render element to be displayed in the VFB during rendering and saved afterward. Type of the elementis specified with the “class” attribute and its name (displayed in the VFB) is specified with “instanceName” attribute:

<renderElement class="[string]" instanceName="[string]">
... (optional parameters, see below)
</renderElement>

<renderElement class="beauty">?<denoiseAmount>[float]</denoiseAmount>

<renderElement class="samplingFocus">?<multiplier>[float]</multiplier> ?<relative>[bool]</relative></renderElement>

<renderElement class="velocity">?<mode>camera|world</mode> ?<multiplier>[float]</multiplier> ?<offset>[float]</offset></renderElement>

<renderElement class="components">+<componentName>[string]</componentName></renderElement>

<renderElement class="zDepth"><minimalT>[float]</minimalT><maximalT>[float]</maximalT></renderElement>

<renderElement class="LightSelect">*<included>[string]</included>?<includeEnvironment>?<includeSun></renderElement>