How To Use The JSON Interface

A detailed overview on using the JSON scene definition format.

Broken down into sections, as they can be found in the default scene.json.

At this time, you should provide all the configuration options in the JSON until I've implemented sane defaults to override instead.

This technical spec for the scene format is volatile, and this documentation may be out of date. Please refer to the example scene file input/scene.json for the latest example of how it works. For now backwards compatibility is not considered, so your custom scene files may break.

Bundling scenes

There is now a useful script available if you have python3 installed on your system.

In the project root, do: ./scripts/bundle.py input/<somefile>.json The script will scan for all assets referenced in that JSON file and bundle a nice portable .zip file for you. Send it to a friend to check out! Better yet, send your scenes to me!

version

Leave at 1.0. Just futureproofing in case features are added later that are not backwards-compatible.

renderer

• threads - Amount of threads to render with. 0 defaults to system logical core count.
• samples - Amount of samples to render. More samples -> Smoother image with less noise.
• bounces - The amount of times a ray can bounce in the scene. This determines reflection depth.
• antialiasing - Enable or disable antialiasing. (Reduces jagged edges)
• tileWidth - Width of the tiles the image is quantised into.
• tileHeight - Height of the tiles the image is quantised into.
• tileOrder - Order the tiles are rendered in. Doesn't affect render time, mostly just helps with debugging when you can decide roughly which part of the image is rendered first. Available options are: normal, random, topToBottom, fromMiddle, toMiddle.
• outputFilePath - The file path in which the output image will be written to, relative to the working directory (Usually the project root)
• outputFileName - Name prefix of the output image file
• fileType - File type of the output image file. Available options are: png and bmp (Stick to PNG as it's losslessly compressed)
• count - The number postfix of the image file
• width - Width of the image in pixels
• height - Height of the image in pixels

display

• enabled - Enable or disable SDL window (Useful for scripts that repeatedly invoke C-ray)
• isFullscreen - Enable or disable fullscreen mode for SDL render preview window
• isBorderless - Enable or disable window borders for SDL render preview window.
• windowScale - Adjust the size of the SDL render preview window. This is a multiplier from 0.0->1.0 (i.e. 0.5 is one half the size of 1.0)

camera

• FOV - Camera field of vision. The smaller the value, the narrower the field of vision.
• focalDistance - Camera focal distance. The distance at which everything is in focus if the aperture is > 0.0f
• aperture - Aperture of the camera.
• transforms - Array of transforms for the camera. (For now, make sure the translate transform is first in this list!)

scene

• ambientColor - This color to every pixel in the final image where the ray didn't hit anything within 20k distance units. The color is linearly interpolated between down and up, and optionally you can put a hdr key in here with a path to a Radiance HDR file, it will be loaded and used as the environment map for realistic lighting. Refer to input/hdr.json for an example of this.
• primitives - Array of geometric primitives to be placed in the scene (spheres, ellipses, etc)
• meshes - Array of 3D meshes to be placed in the scene

Object types and their usage

Transform

Transforms are used to move, rotate and scale most objects, excluding (for now) spheres and lights.

Transform parameters:

• type - Transform type. These are listed below, including the required parameters for each.
• x - X displacement/scale factor, if needed
• y - Y displacement/scale factor, if needed
• z - Z displacement/scale factor, if needed
• degrees - degrees to rotate an object by, if needed
• radians - radians to rotate an object by, if needed
• scale - scale factor to uniformly scale an object by, if needed

Note: If both a degrees and a radians value is provided for a rotation, the degrees value will be used.

Transform types and required parameters for each

• rotateX - Rotate the object in the X axis by N degrees

Required parameters: degrees or radians

• rotateY - Rotate the object in the Y axis by N degrees

Required parameters: degrees or radians

• rotateZ - Rotate the object in the Z axis by N degrees

Required parameters: degrees or radians

• translate - Translate the object (move it around) in 3D Space by +/- X, Y, Z

Required parameters: X, Y, Z, up to 2 can be omitted, defaults to 0.0

• scale - Scale the object by a +/- factor in the X, Y, Z axis

Required parameters: X, Y, Z, up to 2 can be omitted, defaults to 1.0

• scaleUniform - Scale an object uniformly on all axis by a scaling factor

Required parameters: scale

Color

Colors are only used to set the ambient color, and sphere/emitter colors.

Color parameters:

• blackbody - Color temperature in degrees kelvin, i.e. 5900 for daylight. (If this is provided, it will override any other values given.)
• r - Red value, from 0.0 to 1.0
• g - Green value, from 0.0 to 1.0
• b - Blue value, from 0.0 to 1.0
• a - (Optional) Alpha transparency value, from 0.0 to 1.0

Coordinate

Coordinates are only used to set the positions for objects that don't yet use transforms.

coordinate parameters:

• x - X coordinate in space
• y - Y coordinate in space
• z - Z coordinate in space

Primitive

For now we only support spheres, this will be expanded later.

Primitive parameters:

• type - Type of primitive, in this case sphere
• pos - coordinate object, the location of this sphere.
• color - color object, the color of this sphere
• bsdf - The BSDF to use. metal, glass, emissive and lambertian are supported.
• IOR - Index of refraction if it's a glass BSDF
• roughness- Roughness of the surface if it's glass or metal
• intensity - Brightness of the lamp if it is emissive
• radius - The size of this sphere

Mesh

Meshes are the 3D models that you can export from popular programs like Blender.

Mesh parameters:

• fileName - The file name to load from. If not found, will be skipped (with error message)
• bsdf - The BSDF to use. metal, glass, emissive and lambertian are supported.
• IOR - Index of refraction if it's a glass BSDF
• roughness- Roughness of the surface if it's glass or metal
• intensity - Brightness of the lamp if it is emissive
• transforms - Array of transform objects to apply to this mesh. (For now please make sure translate transforms are last in this array! Otherwise you get weird behavior)