Scene Description File Format

Scene description file

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

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

Scene description file is typically 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 file can be found in Cornell Box and Asuna-Scenes.

For more details of forementioned 8 parts, please refer to their corresponding pages.

• State
• Camera
• Light
• Texture
• Mesh
• Material
• Instance
• Shot

Declaration-Reference

The use of textures, materials and meshes is in declaration-reference manner. For example, 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; In addition, 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": ...,
  "film": {
    "resolution": [800, 600]
  },
  ...
}

type specifies which camera model Asuna will use. 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 these 2 parts 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	a postive float number in [0, 180)
➕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

TBD

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 ]
    }
]

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.