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>
regionRemaps the image from the entire image plane to just a region specified by its start/end coordinates. This is different from the image region functionality: when using values inside the 0 0 1 1 region, this zooms into the image, without changing resolution or creating black borders. The values can also go beyond the 0-1 interval to create a shift effect.
minT, maxTSpecifies the minimal/maximal intersection distance - if specified, any objects closer/further to the camera will be ignored by primary rays, creating a slice effect

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>
ClassDescription
alphaSame as the built-in alpha channel
virtualBeauty

Duplicate of the beauty channel. Does not actually allocate extra memory. Can optionally have a different denoising amount value specified:

<renderElement class="beauty">?<denoiseAmount>[float]</denoiseAmount>
renderStampShows the render stamp only
shadowsInverted Shadows from all lights
sourceColorThe input color of the surface before any shading, read from texture/solid color. The node value specifies which component is displayed. It is one of these values: diffuse, translucency, reflect, refract, opacity
normalsDotProductDisplays cosine of angle between incident ray and surface shading normal. Useful for debugging.
normalsDiscrepancyDisplays the difference between shading and geometry normals on a surface. Useful for debugging.
primitiveCoordsDisplays local primitive coordinates. Useful for debugging.
mapCoordsDisplays mapping coordinates of a surface. Node value is a single int specifying which channel is displayed.
samplingFocus

Shows the concentration of samples per pixel in the image. Visualizes what the adaptivity algorithms do, with brighter areas representing more samples used in the area. Has two optional parameters:

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

Shows the geometry velocity either in world or in camera space. Has optional parameters:

<renderElement class="velocity">?<mode>camera|world</mode> ?<multiplier>[float]</multiplier> ?<offset>[float]</offset></renderElement>
worldPositionDisplays position of surface point in world coordinates.
albedoTotal surface reflectivity - sum of all possible SourceColor channels. Surfaces with near-100% albedo are displayed with red tint.
normalsVisualization of the surface normals. The node value specifies what type of normals to display: it either equals shading, or geometry.
normalMapCreates a normal map from difference between shading and geometry normals.
components

Displays selected components of the shaded result. Multiple components can be selected for the single element, in that case they are added up in the result. They are specified as:

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

The allowed string values are emission and {diffuse, translucency, reflect, refract, volumetric}×{direct, indirect} (any combination of one prefix and one suffix - e.g. DiffuseDirect, ReflectIndirect)

rawComponent“Raw” component - direct and indirect illumination not affected by the surface color. It is equal to direct+indirect Components element divided by corresponding SourceColor. Only shows results for one component at time. The parameter specifies which one, and can be one of these values: diffuse, translucency, reflect, refract.
idDisplays IDs visualized as colors based on selected factors. The possible element values are: primitive, instance, geometryGroup, material.
zDepth

Displays the distance of objects from the camera. Has 2 child nodes that specify the minimal (mapped to black) and maximal (mapped to white) distances:

<renderElement class="zDepth"><minimalT>[float]</minimalT><maximalT>[float]</maximalT></renderElement>
texmapRenders a map in a separate buffer. The map is specified as the sole child of the element.
BloomGlareSeparated Bloom and Glare effect.
LightSelect

Lighting from a selected subset of lights. The subset is specified with:

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

- individual lights are named by their “name” (same as include list), plus there is option to include sun and sky separately (since they have no source node).