Scene Description File Format

Scene description file

Scene is described by a json file in Asuna. A skeleton of typical scene description file is shown as below:

{
  "state": { },
  "camera": { },
  "lights": [ ],
  "envmap": { },
  "textures": [ ],
  "materials": [ ],
  "meshes": [ ],
  "instances": [ ],
  "shots": [ ]
}

Generally speaking, scene description file is composed of 7 parts:

• state: settings for path integrator and post processor. This part is required for the scene file.
• camera: settings for camera used in the scene. Up to now, Asuna supports only one camera per scene. This part is required for the scene file.
• ➕lights: all the lights in the scene. This part is optional.
• ➕materials: all the materials in the scene. This part is optional.
• ➕textures: all the textures in the scene. This part is optional.
• meshes: all the meshes in the scene. This part is required for the scene file.
• instances: all the instances in the scene. A instance is composed of a mesh, a material and a transformation used for that mesh. This part is required for the scene file.
• ➕shots: shot is used to describe the pose or extrinsic parameter of the camera and the state used for that pose. A scene can have multiple shots, so you can render multi view images. This part is optional.

Example scene description files can be found in Cornell Box and Asuna-Scenes.

For more details of forementioned parts, please refer to their corresponding sections in this page.

Declaration-Reference

The use of textures, materials and meshes is in declaration-reference manner. That is, if you want to create a material which uses texture A as normal map, you should first do declaration: put A in textures part of scene description file. Another case: if you want to create an instance that uses mesh B and material C, you should put B in meshes part and C in materials part. A example declaration-reference procedure is shown below:

    "textures": [{ "name": "cloth", "path": "textures/Clothes_emissive.png" }],
    "materials": [{ "name": "cloth", "type": "brdf_emissive", "radiance_texture": "cloth"}],
    "meshes": [{ "name": "cloth3", "path": "Cloth3.obj" }],
    "instances": [{ "mesh": "cloth3", "material": "cloth" }]

where texture "cloth" is referenced by material "cloth", mesh "cloth3" and material "cloth" are referenced by instances[0].

State

TBD

Camera

A camera model describes how ray passes through lens, hits the film plane and forms the final image. A typical camera json element is composed of 3 parts.

{
  "type": "perspective",
  "film": { "resolution": [800, 600] },
  "fov": 22.5
}

type specifies which camera model Asuna will use.

Film

key	type	description
resolution	float2	width and height of rendered image

film specifies the properties of film plane. Up to now, it only has resolution which describes the size of output image in [width, height] manner. Following film and type is the camera-model-specific data.

Asuna supports following camera models.

Perspective Camera

key	type	description
type	string	must be "perspective"
film	json
fov	float	field of view
➕aperture	float	radius of camera aperture (default 0.0)
➕focal_distance	float	distance of focal length (default 0.1)

OpenCV Pinhole Camera

key	type	description
type	string	must be "opencv"
film	json
fx	float	focal length in x axis
fy	float	focal length in y axis
cx	float	optical center in x axis
yc	float	optical center in y axis

In fact, fx,fy,cx,cy is equivalent with opencv camera intrinsic matrix K. Note that though loader is ok to load opencv camera json element, it is not supported by the ray tracing pipeline of Asuna now, which corresponds to the ray generation process in src/shaders/raytrace.projective.rgen.

Texture

A texture describes a 2D resources that can be mapped to the object surface.

Asuna supports loading .jpg/.png/.bmp/.tga/.exr/.hdr image as texture.

key	type	description
name	string	brief alias of the texture to be loaded
path	string	absolute/relative path of the texture
➕gamma	float	gamma correction for ldr image, data=pow(texture, gamma) (default 1.0)

Mesh

A mesh describes the graphics primitives. Up to now, Asuna supports only .obj mesh file and will convert all the facets to triangles.

key	type	description
name	string	brief alias of the mesh to be loaded
path	string	absolute/relative path of the mesh
➕recompute_normal	bool	recompute the mesh normal (default false). You'd better do not let Asuna compute normal for the mesh.
➕uv_scale	float2	scale of the vertex texture coordinates, usually useful for a plane mesh (default [1,1])

Light

A light describes the objects that will actively send out emittance and will not bounce rays in the scene.

The design of light is quite complex in Asuna (maybe I will simplify it later):

• For light that has no detection of ray collision (e.g. point light, directional light, spot light), Asuna will only create gpu data src/shared/light.h for that light to make it accessible to ray tracing shaders.

• For light that need to do detection of ray collision (e.g. rectangle light, triangle light, mesh light), Asuna will not only create gpu data src/shared/light.h but also automatically create a mesh/an instance for that light in the same time, so that these lights can be hit in the ray tracing pipeline. The lightId of all the light instances is non-negative number. The material applied to light instance is brdf_lambertian. So, you can find procedure of ray hitting light in src/shaders/bxdf/raytrace.brdf_lambertian.rchit.

Asuna supports following light models.

Triangle Light

key	type	description
type	string	must be "triangle"
radiance	float3	radiance of light
position	float3	original position of triangle
v1	float3	adjacent point of triangle origin
v2	float3	adjacent point of triangle origin

Rectangle Light

Mesh Light

Directional Light

Environment Light

Please refer to envmap section.

Envmap

A envmap describe the surrounding environment light by an image which is typically high dynamic range (e.g. hdr, exr).

key	type	description
path	string	absolute/relative path to environment map.

To change envmap intensity, or to rotate envmap, please refer to State.

Envmap will be later merged into Light.

Material

A material describes how ray behaves when bouncing at surface.

Asuna supports following materials.

Lambertian BRDF

key	type	description
type	string	must be "brdf_lambertian"
➕diffuse_reflectance	float3	diffuse albedo color (default [0,0,0])
➕diffuse_texture	string	name of reference diffuse texture (default NONE)
➕normal_texture	string	name of normal diffuse texture (default NONE)

Instance

An instance describes a combination of mesh, material and transformation.

key	type	description
mesh	string	name of reference mesh
material	string	name of reference material
➕toworld	json	see blow (default no_transformation)

If you want the instance have transformation, you can specify toworld. It is a sequence of simple transformations, which will be applied to the instance successively. A typical toworld sequence is shown below:

"toworld": [
    {
        "type": "rotate",
        "value": [90, 0, -98.5]
    },
    {
        "type": "translate",
        "value": [109.32, 107.883, 38.03 ]
    }
]

Simple Transformation

Every simple transformation requires two keys:

key	type	description
type	string	type of transformation
value	?	depends on type

Asuna supports following simple transformations:

type of transformation	type	value	description
rotate with respect to xyz axis	must be "rotate"	float3	rotate degrees respect to xyz axis, rotation is applied in xyz order
scale	must be "scale"	float3	xyz scale
translate	must be "translate"	float3	xyz translation
transformation matrix	must be "matrix"	float16	in row order (m[0,0], m[0,1]...) with translate vector=m[0:3,3]
rotate with respect to x axis	must be "rotx"	float	rotate degrees respect to x axis
rotate with respect to y axis	must be "roty"	float	rotate degrees respect to y axis
rotate with respect to z axis	must be "rotz"	float	rotate degrees respect to z axis

Shot

TBD

This page is still in progress.